API Reference
The Vois AI REST API lets you manage agents, skills, integrations, and conversations programmatically.
Base URL
https://dev.api.vois-ai.com/api
Authentication
All API requests require a session cookie or a bearer token. Include the Authorization header:
Authorization: Bearer <your-token>
Tokens can be obtained via the Keycloak token endpoint.
Project scoping
Most resources are scoped to a project. Include the project ID in the URL path:
/api/projects/{project_id}/agents
/api/projects/{project_id}/skills
/api/projects/{project_id}/tools
Endpoints
Agents
| Method | Path | Description |
|---|---|---|
GET | /projects/{id}/agents | List all agents |
POST | /projects/{id}/agents | Create an agent |
GET | /projects/{id}/agents/{agent_id} | Get an agent |
PUT | /projects/{id}/agents/{agent_id} | Update an agent |
DELETE | /projects/{id}/agents/{agent_id} | Delete an agent |
Skills
| Method | Path | Description |
|---|---|---|
GET | /projects/{id}/skills | List all skills |
POST | /projects/{id}/skills | Create a skill |
GET | /projects/{id}/skills/{skill_id} | Get a skill |
PUT | /projects/{id}/skills/{skill_id} | Update a skill |
DELETE | /projects/{id}/skills/{skill_id} | Delete a skill |
Integrations
| Method | Path | Description |
|---|---|---|
GET | /tool-templates | List available integration templates |
GET | /projects/{id}/tools | List installed integrations |
POST | /projects/{id}/tools | Install an integration |
DELETE | /projects/{id}/tools/{tool_id} | Uninstall an integration |
File Upload
| Method | Path | Description |
|---|---|---|
POST | /projects/{id}/upload | Upload a file (image or PDF) |
Request: multipart/form-data with a file field.
Response:
{
"url": "https://storage.blob.core.windows.net/uploads/...",
"filename": "document.pdf",
"mime_type": "application/pdf",
"size_bytes": 204800
}
Rate limits
| Plan | Requests per minute |
|---|---|
| Starter | 60 |
| Pro | 300 |
| Enterprise | Custom |
Errors
The API returns standard HTTP status codes:
| Code | Meaning |
|---|---|
200 | Success |
400 | Bad request — check the request body |
401 | Unauthorized — invalid or missing token |
403 | Forbidden — insufficient permissions |
404 | Not found |
422 | Validation error — see detail field |
500 | Internal server error |
Error responses follow this shape:
{
"detail": "Human-readable error message"
}