API reference
Genisys Developer API 1.0.0, generated from contracts/developer-api.v1.json when this site is built.
Local API served by the Genisys desktop app on 127.0.0.1 (off until enabled in the Developer console). Authenticate with an API key: Authorization: Bearer gsk_test_… (test mode) or gsk_live_… (production). Test keys see Test, Preview and Production plugins and their runs are marked test; live keys see Production plugins only. Every key has scopes, optional project limits, a per-minute rate limit and optional daily/monthly token budgets.
Base URL: http://127.0.0.1:4319 (Default local port (configurable in the Developer console)). Authentication: Authorization: Bearer gsk_test_… or gsk_live_….
GET /v1/projects
Projects this key may use (scope projects:read)
- operationId
listProjects- Scope
projects:read
Request body
No body.
Response 200: OK (application/json)
| Field | Type | Required | Notes |
|---|---|---|---|
data | array of Project | yes |
Errors: the error envelope with any of its codes.
POST /v1/runs
Start an agent run and wait for it to finish (scope runs:write). Counts against the key's token budget.
- operationId
createRun- Scope
runs:write
Parameters
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
Idempotency-Key | header | string | no | max length 100 |
Request body (application/json, required)
| Field | Type | Required | Notes |
|---|---|---|---|
projectId | string | yes | |
prompt | string | yes | max length 20000 |
agentId | string | no |
Response 200: Finished run (application/json)
| Field | Type | Required | Notes |
|---|---|---|---|
(body) | Run | yes |
Errors: the error envelope with any of its codes.
GET /v1/runs/{id}
A run started with this key (scope runs:read)
- operationId
getRun- Scope
runs:read
Parameters
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string | yes |
Request body
No body.
Response 200: OK (application/json)
| Field | Type | Required | Notes |
|---|---|---|---|
(body) | Run | yes |
Errors: the error envelope with any of its codes.
GET /v1/usage
This key's token use today and this month, with its budgets (scope usage:read)
- operationId
getUsage- Scope
usage:read
Request body
No body.
Response 200: OK (application/json)
Errors: the error envelope with any of its codes.
GET /v1/plugins
Plugins this key can invoke (scope plugins:invoke)
- operationId
listPlugins- Scope
plugins:invoke
Request body
No body.
Response 200: OK (application/json)
| Field | Type | Required | Notes |
|---|---|---|---|
data | array of Plugin | yes |
Errors: the error envelope with any of its codes.
POST /v1/plugins/{id}/invoke
Run one plugin tool in the sandbox (scope plugins:invoke)
- operationId
invokePlugin- Scope
plugins:invoke
Parameters
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string | yes |
Request body (application/json, required)
| Field | Type | Required | Notes |
|---|---|---|---|
tool | string | yes | |
input | object | yes |
Response 200: OK (application/json)
| Field | Type | Required | Notes |
|---|---|---|---|
(body) | InvokeResult | yes |
Errors: the error envelope with any of its codes.
Errors
Every failure has the body { "error": { "code": string, "message": string } }. Branch on the code; the message is written for people.
| Code | Meaning |
|---|---|
unauthorized | No key, an unknown key, or a revoked key. |
forbidden | The key lacks the operation’s scope, or the project is outside the key’s project limit. |
not_found | The run or plugin does not exist for this key. |
invalid_request | The request body or parameters do not match this reference. |
budget_exceeded | The key’s daily or monthly token budget is spent. |
rate_limited | The key made more requests in the last minute than its per-minute limit. |
plugin_failed | The plugin tool threw, timed out or returned output that is too large. |
internal | Something failed inside Genisys. |
Schemas
Error
| Field | Type | Required | Notes |
|---|---|---|---|
error | object | yes | |
error.code | string | yes | one of: unauthorized, forbidden, not_found, invalid_request, budget_exceeded, rate_limited, plugin_failed, internal |
error.message | string | yes |
Project
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | |
name | string | yes | |
description | string | no | |
dataMode | string | yes | one of: local-only, cloud-allowed |
Usage
| Field | Type | Required | Notes |
|---|---|---|---|
inputTokens | integer | yes | |
outputTokens | integer | yes | |
total | integer | yes | |
calls | integer | yes |
Run
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | |
projectId | string | yes | |
agentId | string | null | no | |
status | string | yes | one of: queued, running, succeeded, failed, cancelled, paused |
output | string | null | yes | |
failure | string | null | no | |
usage | Usage | yes | |
test | boolean | yes | |
createdAt | string | yes | format date-time |
Plugin
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | |
name | string | yes | |
version | string | yes | |
stage | string | yes | one of: test, preview, production |
tools | array of object | yes | |
tools[].name | string | yes | |
tools[].description | string | yes | |
tools[].input | object | no |
InvokeResult
| Field | Type | Required | Notes |
|---|---|---|---|
output | any JSON | yes | |
logs | array of string | yes | |
ms | integer | yes |