Overview
Every call is an HTTP POST with a JSON body, under /api/ on the agent server. The GUI uses nothing else, so everything the GUI 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 | Anyone |
/api/exec/ | Search, run an agent, read a conversation | Any signed-in user |
/api/user/ | The caller's profile, password and conversations | Any signed-in user |
/api/dev/ | Drafts and draft validation, agents, descriptions, notifications, help messages | Developers and above |
/api/admin/ | Users, roles, configuration, profiles, 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 |
The role required by each call is the role the GUI requires for the same action; see Users and roles. The check is made by Search2o Cloud 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, and with errorMessage when success is false. The message is written for the person using the client and can be shown as is.
{ "success": false, "errorMessage": "This conversation has expired. Please start a new one." }A failed call carries an HTTP error status as well. 422 means a bad request or an error inside the agent. 401 or 403 means a missing or insufficient sign-in. 500 means the server or the cloud is at fault. When the caller's session has expired, the response also carries mustLogin: true; sign in again and repeat the call.
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 lets each endpoint be tried 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 up
GET /health needs no 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"}. See Agent server sizing for what its response time says about a busy server.