Skip to main content

​
Build on published Mosoo Agents

Use the Mosoo API to call an Agent after it has been configured and published in Mosoo. Your application provides a caller token and the published Agent’s agentId; Mosoo starts a Thread, runs the Agent, and exposes the public events and files for that Thread. This is the same integration surface behind the API Access entry in the Agent publish menu.
The API only works with published Agents. Agent setup, model provider connections, and channel bindings are managed in Mosoo before you call these endpoints.

1. Publish an Agent

Configure the Agent in Mosoo, connect its model provider, and publish it so it receives an agentId.

2. Create a token

Use a Human PAT for user-owned calls or an Organization Service token for server-side jobs.

3. Start a Thread

Create a Thread with an initial message, then send events, attach files, and read results.

​
First request

Create a Thread by combining your access token with the published Agent ID. 
curl -X POST "https://mosoo.ai/api/v1/agents/$MOSOO_AGENT_ID/threads" \
  -H "Authorization: Bearer $MOSOO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ticket-182-create-thread" \
  -d '{
    "client_external_ref": "ticket-182",
    "input": {
      "type": "user.message",
      "content": [
        {
          "type": "text",
          "text": "Triage this customer escalation and suggest next steps."
        }
      ]
    }
  }'
The response includes a thread.id and the first run. Use that Thread ID for follow-up messages, event reads, file attachment, and lifecycle actions.

Run the full quickstart

Set environment variables, create a Thread, send another user message, and read the event log.

​
Core concepts

Published Agent

The callable Agent identity. Copy its agentId from the Agent’s API Access panel after publishing.

Caller token

A Human PAT or Organization Service token. The token identifies the caller; it does not change which published Agent is run or how that Agent is configured.

Thread

The conversation container created through the API. Threads track messages, files, run status, attribution, and lifecycle state.

Events

The stable public log for API consumers. Send user messages or permission decisions, then read Agent-visible results from the Thread event list.

​
What you can build

Use the API when a published Agent should become part of another product or workflow:
  • Start an Agent from your own server when a ticket, order, alert, or job appears.
  • Project work to a user through attributed_user_id when an Organization Service token is allowed to do so.
  • Attach files to a Thread before or during a run.
  • Poll the public event log for Agent messages, tool status, file changes, usage updates, and run completion.
  • Keep external systems in sync with client_external_ref and Idempotency-Key.

​
API capabilities

Create and list Threads

POST /agents/{agentId}/threads creates a Thread and initial run. GET /agents/{agentId}/threads lists Threads visible to the caller.

Send and read events

POST /threads/{threadId}/events sends user messages, permission decisions, or interrupts. GET /threads/{threadId}/events reads the public event log.

Attach files

Add, list, and remove Thread files. API-added files are attachments; Agent-produced files are returned as artifacts.

Manage lifecycle

Retrieve, archive, unarchive, or delete a Thread when your integration no longer needs it active.

​
Access model

Every request is evaluated against the published Agent and the caller token:
  • The Agent must exist, be published, and expose API access.
  • The caller token must be valid and not revoked.
  • Human callers must still pass Organization membership and Agent access checks.
  • Organization Service tokens must be explicitly allowed to call selected published Agents.
  • Runs use the published Agent owner’s configured capabilities.

Understand tokens and access

Read how Human PATs, Organization Service tokens, Agent access modes, attribution, and owner settings fit together.