Skip to main content

Management API

The management API lets your own server do what the console does with a project's agents, skills, tools, channels and uploads. For example, you can create an agent, attach skills and tools to it, and add a channel from a script or a CI job.

It uses the same project API keys as the widget API, but the key needs management permissions. A key never gets these by default.

Give a key management permissions​

  1. Sign in at app.voisx.ai and open your project.
  2. Go to Settings › API keys.
  3. Generate a key, or pick an existing one, and select Permissions.
  4. Under Management API, tick what the key needs, then select Save permissions.

Only project admins and owners can give a key management permissions, or change a key that has them. Anyone else gets 403.

warning

A key with management permissions can change and delete what is in your project. Keep it on your server, in a secret manager. Never put it in a web page or an app. Use a separate key, with widget permissions only, for your website.

Permissions​

Each area has a read permission and a write permission. Read covers GET requests. Write covers every other method, which includes running and testing tools.

PermissionLets the key
agents:readList agents and read their settings and prompt history
agents:writeCreate, update and delete agents, and restore a prompt version
skills:readList skills and the skills attached to each agent
skills:writeCreate, update and delete skills, and attach them to agents
tools:readList tools, their versions, usage and connections
tools:writeCreate, update, test and run tools, and assign them to agents
channels:readList channels and form submissions
channels:writeCreate, update and delete channels
uploads:writeUpload images and PDFs

A key can hold widget and management permissions together, but it is safer to keep them on separate keys.

Send the key​

Send the key in the X-API-Key header, or as a bearer token. Management requests go to the /api prefix on your region's host.

curl https://in.api.voisx.ai/api/projects/1042/agents/ \
-H "X-API-Key: $VOISX_API_KEY"

1042 is your project ID. You can find it in the console URL, for example app.voisx.ai/project/1042/....

Scope​

A key reaches only its own project:

  • A project ID in the path that is not the key's project returns 404.
  • An agent, tool or channel ID from another project also returns 404.
  • If the key is limited to some agents, routes with an agent ID in the path work only for those agents. Other agents return 403. The agent list shows only the allowed agents.

Domain restrictions apply only when a request has an Origin header, which means it comes from a browser. Server-side requests have no Origin header, so the restriction is not checked.

Rate limits are the same as for the widget API. Widget and management requests made with the same key count towards the same limits.

Endpoints​

All paths start with https://<region host>/api.

Agents​

MethodPathPermission
GET/projects/{project_id}/agents/agents:read
POST/projects/{project_id}/agents/agents:write
GET/projects/{project_id}/agents/templatesagents:read
POST/projects/{project_id}/agents/from-template/{template_id}agents:write
GET/agents/{agent_id}agents:read
PUT/agents/{agent_id}agents:write
DELETE/agents/{agent_id}agents:write
GET/agents/{agent_id}/prompt-versionsagents:read
GET/agents/{agent_id}/prompt-versions/{version_id}agents:read
POST/agents/{agent_id}/prompt-versions/{version_id}/restoreagents:write
POST/agents/{agent_id}/generate-system-promptagents:write

Skills​

MethodPathPermission
GET/projects/{project_id}/skillsskills:read
POST/projects/{project_id}/skillsskills:write
GET/projects/{project_id}/skills/{skill_id}skills:read
PUT/projects/{project_id}/skills/{skill_id}skills:write
DELETE/projects/{project_id}/skills/{skill_id}skills:write
GET/agents/{agent_id}/skillsskills:read
POST/agents/{agent_id}/skills/{skill_id}skills:write
DELETE/agents/{agent_id}/skills/{skill_id}skills:write

Tools​

MethodPathPermission
GET/projects/{project_id}/toolstools:read
POST/projects/{project_id}/toolstools:write
POST/projects/{project_id}/tools/install-templatetools:write
GET/projects/{project_id}/tools/{tool_id}tools:read
PATCH/projects/{project_id}/tools/{tool_id}tools:write
DELETE/projects/{project_id}/tools/{tool_id}tools:write
POST/projects/{project_id}/tools/{tool_id}/testtools:write
GET/projects/{project_id}/tools/{tool_id}/versionstools:read
GET/projects/{project_id}/tool-connectionstools:read
POST/projects/{project_id}/tool-connectionstools:write
GET/agents/{agent_id}/toolstools:read
POST/agents/{agent_id}/tools/{tool_id}tools:write
DELETE/agents/{agent_id}/tools/{tool_id}tools:write

Channels​

MethodPathPermission
GET/projects/{project_id}/channelschannels:read
POST/projects/{project_id}/channelschannels:write
GET/projects/{project_id}/channels/{channel_id}channels:read
PUT/projects/{project_id}/channels/{channel_id}channels:write
DELETE/projects/{project_id}/channels/{channel_id}channels:write
GET/projects/{project_id}/channels/{channel_id}/form/submissionschannels:read

Uploads​

MethodPathPermission
POST/projects/{project_id}/uploaduploads:write

The upload takes a multipart/form-data body with one file field: an image or a PDF of up to 20 MB. The response's url is a public link to the file.

Chatting with an agent from the Playground is not part of the management API. To talk to an agent from your own client, use sessions.

Errors​

StatusWhen
401The key is unknown, revoked or expired, or it lacks the permission the request needs. detail names the missing permission.
403The agent is not allowed for this key, or the endpoint does not accept API keys.
404The project, or the agent, tool or channel, does not exist or is in another project.
429The key went over its rate limit.

See Errors for the body shape.

Was this page helpful?