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
- Sign in at app.voisx.ai and open your project.
- Go to Settings › API keys.
- Generate a key, or pick an existing one, and select Permissions.
- 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.
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.
| Permission | Lets the key |
|---|---|
agents:read | List agents and read their settings and prompt history |
agents:write | Create, update and delete agents, and restore a prompt version |
skills:read | List skills and the skills attached to each agent |
skills:write | Create, update and delete skills, and attach them to agents |
tools:read | List tools, their versions, usage and connections |
tools:write | Create, update, test and run tools, and assign them to agents |
channels:read | List channels and form submissions |
channels:write | Create, update and delete channels |
uploads:write | Upload 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
- Node.js
- Python
curl https://in.api.voisx.ai/api/projects/1042/agents/ \
-H "X-API-Key: $VOISX_API_KEY"
const res = await fetch("https://in.api.voisx.ai/api/projects/1042/agents/", {
headers: { Authorization: `Bearer ${process.env.VOISX_API_KEY}` },
});
const agents = await res.json();
import os
import requests
res = requests.get(
"https://in.api.voisx.ai/api/projects/1042/agents/",
headers={"X-API-Key": os.environ["VOISX_API_KEY"]},
)
agents = res.json()
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
| Method | Path | Permission |
|---|---|---|
GET | /projects/{project_id}/agents/ | agents:read |
POST | /projects/{project_id}/agents/ | agents:write |
GET | /projects/{project_id}/agents/templates | agents: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-versions | agents:read |
GET | /agents/{agent_id}/prompt-versions/{version_id} | agents:read |
POST | /agents/{agent_id}/prompt-versions/{version_id}/restore | agents:write |
POST | /agents/{agent_id}/generate-system-prompt | agents:write |
Skills
| Method | Path | Permission |
|---|---|---|
GET | /projects/{project_id}/skills | skills:read |
POST | /projects/{project_id}/skills | skills: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}/skills | skills:read |
POST | /agents/{agent_id}/skills/{skill_id} | skills:write |
DELETE | /agents/{agent_id}/skills/{skill_id} | skills:write |
Tools
| Method | Path | Permission |
|---|---|---|
GET | /projects/{project_id}/tools | tools:read |
POST | /projects/{project_id}/tools | tools:write |
POST | /projects/{project_id}/tools/install-template | tools: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}/test | tools:write |
GET | /projects/{project_id}/tools/{tool_id}/versions | tools:read |
GET | /projects/{project_id}/tool-connections | tools:read |
POST | /projects/{project_id}/tool-connections | tools:write |
GET | /agents/{agent_id}/tools | tools:read |
POST | /agents/{agent_id}/tools/{tool_id} | tools:write |
DELETE | /agents/{agent_id}/tools/{tool_id} | tools:write |
Channels
| Method | Path | Permission |
|---|---|---|
GET | /projects/{project_id}/channels | channels:read |
POST | /projects/{project_id}/channels | channels: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/submissions | channels:read |
Uploads
| Method | Path | Permission |
|---|---|---|
POST | /projects/{project_id}/upload | uploads: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
| Status | When |
|---|---|
401 | The key is unknown, revoked or expired, or it lacks the permission the request needs. detail names the missing permission. |
403 | The agent is not allowed for this key, or the endpoint does not accept API keys. |
404 | The project, or the agent, tool or channel, does not exist or is in another project. |
429 | The key went over its rate limit. |
See Errors for the body shape.