Global-api

About 1345 wordsAbout 4 min

Generated from docs/.vuepress/openapi.json. Refresh with npm run gen:api. Back to overview.

`GET /api/v1/global-api-keys` — List the global API keys

Tags: Global-api

Responses

Status	Description
`200`	Key metadata. Secrets are never returned.
`403`	The caller is not a global admin.

`POST /api/v1/global-api-keys` — Mint a global API key

Tags: Global-api

Request body

application/json — required

Field	Type	Required	Description
`name`	string	yes	At most 100 characters.

Responses

Status	Description
`201`	The key, with its plaintext secret. Shown once.
`403`	The caller is not a global admin.
`422`	The name was missing or too long.

`DELETE /api/v1/global-api-keys/{keyId}` — Revoke a global API key

Tags: Global-api

Path parameters

Name	Type	Required	Description
`keyId`	string	yes

Responses

Status	Description
`200`	Revoked. Idempotent — the same body whether or not the key existed.
`403`	The caller is not a global admin.

`GET /api/v1/global-api/agents` — List the agents this key may reach

Tags: Global-api

Responses

Status	Description
`200`	The agents in the key’s reach.

`POST /api/v1/global-api/agents` — Create an agent from the import format

Tags: Global-api

Request body

application/json — required

Field	Type	Required	Description
`agent`	object	yes	The agent block of the import format.
`name`	string	no
`tools`	array of object	no
`group_id`	integer	no	The owning group. The global surface only.

Responses

Status	Description
`201`	The agent was created.
`404`	The group does not exist, or is outside the key’s reach.
`422`	The payload is not a usable import format.

`GET /api/v1/global-api/agents/{agentId}` — Read an agent in the import format

Tags: Global-api

Path parameters

Name	Type	Required	Description
`agentId`	integer	yes

Responses

Status	Description
`200`	The agent, as an import-format payload.
`404`	No such agent, or not one this key may reach.

`PATCH /api/v1/global-api/agents/{agentId}` — Update an agent from the import format

Tags: Global-api

Path parameters

Name	Type	Required	Description
`agentId`	integer	yes

Request body

application/json — required

Field	Type	Required	Description
`agent`	object	no	The agent fields to write.
`name`	string	no
`tools`	array of object	no

Responses

Status	Description
`200`	The agent was updated.
`404`	No such agent, or not one this key may reach.
`422`	The payload is not a usable import format.

`DELETE /api/v1/global-api/agents/{agentId}` — Delete an agent

Tags: Global-api

Path parameters

Name	Type	Required	Description
`agentId`	integer	yes

Responses

Status	Description
`200`	The agent was deleted.
`404`	No such agent, or not one this key may reach.

`GET /api/v1/global-api/chats` — List the chats this key may reach

Tags: Global-api

Query parameters

Name	Type	Required	Description
`since`	string	no	ISO-8601 timestamp; only chats updated after it.
`page`	integer	no
`per_page`	integer	no

Responses

Status	Description
`200`	One page of chats, newest first. 25 per page by default.
`422`	`since` was not a parseable date.

`POST /api/v1/global-api/chats` — Start a chat with one of the agents this key reaches

Tags: Global-api

Request body

application/json — required

Field	Type	Required	Description
`agent_id`	integer	yes	The agent to talk to.
`text`	string	yes	The user message.
`media_ids`	array of string	no
`files`	array of object	no	Inline attachments as data URLs.
`callback_url`	string (uri)	no
`max_steps`	integer	no
`effort`	string \| null	no	The reasoning effort for this message. Omit it and the configuration default applies; an empty string asks for the model default. A level the agent’s LLM driver does not offer is refused with 422 EFFORT_LEVEL_UNSUPPORTED; GET /api/v1/agents/{id}/effort lists the levels it offers. One of `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, `""`.

Responses

Status	Description
`202`	The chat was queued.
`404`	No such agent, or not one this key may reach.
`422`	The request body was not usable.

`POST /api/v1/global-api/chats/{chatId}/answer` — Answer the agent’s question

Tags: Global-api

Path parameters

Name	Type	Required	Description
`chatId`	integer	yes

Request body

application/json — required

Field	Type	Required	Description
`tool_call_id`	string	yes
`content`	string	yes

Responses

Status	Description
`202`	Answer recorded; the chat is queued again.
`404`	No such chat on this agent.
`409`	The chat is not awaiting input.

`POST /api/v1/global-api/chats/{chatId}/approve` — Approve pending tool calls

Tags: Global-api

Path parameters

Name	Type	Required	Description
`chatId`	integer	yes

Request body

application/json — required

Field	Type	Required	Description
`decisions`	array of object	yes

Responses

Status	Description
`202`	Approval recorded; the chat is queued again.
`404`	No such chat on this agent.
`409`	The chat is not pending approval.

`GET /api/v1/global-api/chats/{chatId}/messages` — User messages and answers only

Tags: Global-api

Path parameters

Name	Type	Required	Description
`chatId`	integer	yes

Query parameters

Name	Type	Required	Description
`since_sequence`	integer	no

Responses

Status	Description
`200`	The conversation, tool calls omitted.
`404`	No such chat on this agent.

`POST /api/v1/global-api/chats/{chatId}/messages` — Continue a chat

Tags: Global-api

Path parameters

Name	Type	Required	Description
`chatId`	integer	yes

Request body

application/json — required

Field	Type	Required	Description
`text`	string	yes
`media_ids`	array of string	no
`additional_steps`	integer	no
`effort`	string \| null	no	The reasoning effort for this message. Omit it and the configuration default applies; an empty string asks for the model default. A level the agent’s LLM driver does not offer is refused with 422 EFFORT_LEVEL_UNSUPPORTED; GET /api/v1/agents/{id}/effort lists the levels it offers. One of `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, `""`.

Responses

Status	Description
`202`	The follow-up was queued.
`404`	No such chat on this agent.
`409`	The chat is not in a state that can be continued.

`POST /api/v1/global-api/chats/{chatId}/reject` — Reject pending tool calls

Tags: Global-api

Path parameters

Name	Type	Required	Description
`chatId`	integer	yes

Request body

application/json — optional

Field	Type	Required	Description
`reason`	string	no

Responses

Status	Description
`202`	Rejection recorded.
`404`	No such chat on this agent.
`409`	The chat is not pending approval.

`GET /api/v1/global-api/chats/{chatId}/status` — Status and final answer

Tags: Global-api

Path parameters

Name	Type	Required	Description
`chatId`	integer	yes

Responses

Status	Description
`200`	Status, answer, and any block.
`404`	No such chat on this agent.

`GET /api/v1/global-api/chats/{chatId}/transcript` — Everything the admin UI shows

Tags: Global-api

Path parameters

Name	Type	Required	Description
`chatId`	integer	yes

Query parameters

Name	Type	Required	Description
`since_sequence`	integer	no

Responses

Status	Description
`200`	Tool calls, thinking, usage totals.
`404`	No such chat on this agent.

`GET /api/v1/global-api/groups` — List every group

Tags: Global-api

Responses

Status	Description
`200`	Every group in the install.

`POST /api/v1/global-api/groups` — Create a group

Tags: Global-api

Request body

application/json — required

Field	Type	Required	Description
`name`	string	yes
`description`	string	no

Responses

Status	Description
`201`	The group was created.
`403`	The key has no owner to create a group with.
`422`	The name was missing.

`GET /api/v1/global-api/groups/{groupId}` — Read a group

Tags: Global-api

Path parameters

Name	Type	Required	Description
`groupId`	integer	yes

Responses

Status	Description
`200`	The group.
`404`	Group not found.

`PATCH /api/v1/global-api/groups/{groupId}` — Update a group

Tags: Global-api

Path parameters

Name	Type	Required	Description
`groupId`	integer	yes

Request body

application/json — optional

Field	Type	Required
`name`	string	no
`description`	string \| null	no
`information`	string \| null	no

Responses

Status	Description
`200`	The group was updated.
`404`	Group not found.
`422`	The name was empty.

`DELETE /api/v1/global-api/groups/{groupId}` — Delete a group

Tags: Global-api

Path parameters

Name	Type	Required	Description
`groupId`	integer	yes

Responses

Status	Description
`200`	The group was deleted.
`404`	Group not found.
`409`	The group still owns agents.

`POST /api/v1/global-api/media` — Upload a file for one of the agents this key reaches

Tags: Global-api

Request body

multipart/form-data — required

Field	Type	Required	Description
`file`	binary	no	File part.
`agent_id`	integer	no

Responses

Status	Description
`201`	The asset was ingested.
`400`	No file was sent under “file”.
`404`	No such agent, or not one this key may reach.
`415`	The file type is not in the agent’s allowlist.

`GET /api/v1/global-api/media/{mediaId}` — Fetch a media asset this key may read

Tags: Global-api

Path parameters

Name	Type	Required	Description
`mediaId`	string	yes
`mediaId`	string	yes

Responses

Status	Description
`200`	The asset bytes.
`404`	No such asset, or not one this key may read.