REST API

Base URL and auth

The API lives under:

https://universalchatbot.com/api/agent/v1

Every request carries your token as a bearer header:

Authorization: Bearer <your-token>

There is no workspace header. Each call names its workspace in the request body. You need to create an access token first.

List tools

Ask which tools your token may call:

curl https://universalchatbot.com/api/agent/v1/tools \
  -H "Authorization: Bearer <your-token>"

The response lists each tool with its name, description, required scope, input schema, and output schema, filtered by your token's scopes. The Tool catalog is the same set in a readable form.

List your workspaces

Every other tool needs a workspace, so find out which ones this token can reach:

curl -X POST https://universalchatbot.com/api/agent/v1/tools/workspaces.list \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{"arguments": {}}'

Each workspace comes back with its subdomain, name, the role you hold there, and the scopes that apply to this token in it. The subdomain is what you pass to every other tool.

Call a tool

POST to the tool by name with an arguments object that names the workspace:

curl -X POST https://universalchatbot.com/api/agent/v1/tools/knowledge.search \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{"arguments": {"workspace": "<workspace>", "query": "refund policy"}}'

workspace is the subdomain from workspaces.list. Every tool other than workspaces.list requires it, and consecutive calls can name different workspaces on the same token.

Responses

A successful call returns the tool's result, in the shape its output schema describes:

{ "result": { ... } }

A failed call returns an error instead, with a type that says what went wrong:

{ "error": { "type": "WorkspaceError", "message": "...", "details": [] } }

• WorkspaceError: the call named no workspace, or one this token cannot reach.
• ScopeError: the token does not hold the tool's scope in that workspace.
• ValidationError: the arguments do not match the tool's input schema, or a record was not found; details lists what failed.

A missing or invalid token is refused before any tool runs.