Overview
Every call under /api/ on the agent server is an HTTP POST with a JSON body. The UI uses nothing else, so everything the UI does is available to your own code.
Endpoint groups
| Prefix | What is there | Who may call it |
|---|---|---|
/api/auth/ | Sign-in, password reset, the account name, the UI’s configuration, the connect flow for integrations | Anyone |
/api/exec/ | Search and run an agent | Any signed-in user |
/api/user/ | The caller's profile, password, conversations and integration tokens | Any signed-in user |
/api/dev/ | Drafts and draft validation, agents, descriptions, profiles, the audit log, messages to Search2o | Developers and above |
/api/admin/ | Users, roles, service accounts, configuration, the license, freezing the account | Administrators and the owner |
/api/reports/ | The four reports and their detail views | Developers; the usage report needs an administrator |
/api/owner/ | The account, invoices, the paid service, deleting the account | The owner |
Each call needs the role the UI needs for the same action; see Users and roles. Search2o Cloud checks the role on every call.
Requests and responses
A request body is a JSON object. A body with a field the endpoint does not know is rejected with status 422, so a typo in a field name cannot pass silently. Every response is a JSON object with success. When success is false, the response carries error, and error.message is written for the person using the client and can be shown as is. error.path names the command where an error inside an agent happened, and error.cause and error.data carry details when there are any.
{ "success": false, "error": { "message": "This conversation has expired. Please start a new one.", "data": {} } }A failed call carries an HTTP error status as well. 422 means a bad request or an error inside the agent. 401 means the caller is not signed in, or the session has expired: sign in again and repeat the call. 403 means the role does not allow the call. 500 means the server or the cloud is at fault.
The schema
A running server serves its OpenAPI schema at /openapi.json. The schema lists every endpoint with its request and response models, and is the input for a generated client or for an LLM that calls the API. The same server renders the schema for people: Swagger UI at /docs sends requests from the browser, and ReDoc at /redoc is a reference to read. All three paths can be moved or switched off in the Agent servers configuration. See Creating your own client and Automating tasks with an LLM.
Checking that a server is running
GET /health does not require sign-in and is answered by the agent server itself, so a load balancer or a monitor can use it as a health check. It reaches nothing outside the agent server, and the response is {"status": "ok"}. Agent server sizing says what its response time tells you about a busy server.