Agent API Endpoints
How a published mosoo Agent becomes callable from the public API.
An Agent API Endpoint is the public API entry point for a published mosoo Agent. Your application calls it with agentId and a mosoo API token.
What must exist
A valid Agent API Endpoint has:
- A real Agent ID.
- Agent status
published. - A live API endpoint version.
- An owning Project owned by the API token owner.
- Matching Agent owner and Project owner.
If the Agent is not published, mosoo returns 409 agent_not_published. If the Agent has no live API endpoint version, mosoo returns 409 service_inactive. If the token owner does not own the Agent's Project, mosoo returns 403 forbidden.
agentId
Get agentId from the Agent API Access panel in mosoo. In v1, agentId is a bare ULID:
01J00000000000000000000001Do not add an agent_ prefix. The same bare-ULID rule applies to threadId, fileId, and runId.
What the endpoint owns
The Agent API Endpoint owns the runtime boundary:
| mosoo owns | Your application owns |
|---|---|
| Published Agent configuration, model provider setup, tool execution, sandbox/runtime behavior, Agent memory/runtime state, and public event generation. | Product UI, backend APIs, jobs, app-side users, business logic, storage, thread.id persistence, and client-owned correlation IDs. |
Requests cannot override model provider credentials, tools, runtime settings, or Agent configuration. Change those in mosoo, then publish the Agent again.
First API call
Create a Thread on the Agent API Endpoint:
POST /api/v1/agents/{agentId}/threadsUse input to queue the first Run immediately, or omit input to create an empty IDLE Thread.
Authentication and access
API token checks and resource visibility.
Create a Thread
Full endpoint reference.
Threads and Runs
Thread and Run lifecycle state.
Application keys must belong to the Agent’s Project. See Authentication and access for key creation and migration.