Mosoo API for coding agents

Use this document when integrating an existing, published Mosoo Agent into application code through the public API.

Integration scope

This document only covers API calls between application code and an existing Mosoo Agent: sending inputs, attaching files, reading outputs, and handling public API errors.

It does not cover:

• Creating, configuring, or publishing Agents.
• Managing Mosoo Apps.
• Managing Agent lifecycle, versions, readiness, runtime settings, model providers, tools, or channels.
• Any other Mosoo product surface outside the public API used to pass input to an Agent and read output from it.

This document is also not the source for secrets or live resource IDs. Do not invent API tokens, agentId, threadId, fileId, or runId values. Use values supplied by the user, environment variables, Mosoo UI, or Mosoo CLI when available.

This document is not a replacement for the raw OpenAPI document when generating clients or validating every schema detail. Use the raw OpenAPI for code generation and strict schema validation.

Integration model

Mosoo is the Agent runtime. The published Agent runs inside a Mosoo-managed sandbox, and your application backend and product code should call that sandboxed Agent through the public API.

Build the app-side integration layer around Mosoo Threads, events, files, and public error handling. Your application can still own backend APIs, jobs, business logic, user flows, and data storage around the sandboxed Agent. For a Mosoo Agent integration, do not implement a parallel Agent layer, sandbox, model loop, planner, tool runner, memory system, lifecycle manager, or provider integration in your application.

Primary contract:

• Human docs: /docs, /docs/quickstart, /docs/auth-and-access, /docs/agent-api-endpoints, /docs/threads-and-runs, /docs/events-and-streaming, /docs/files, /docs/errors-and-limits
• Raw OpenAPI: /docs/openapi/mosoo-openapi.en.generated.json
• API version: v1
• Base URL used in examples: https://try.mosoo.ai/api/v1

Do not infer request fields that are not listed here or in the raw OpenAPI. The public API rejects unsupported fields.

What Mosoo exposes

Mosoo exposes published Agents through Thread-based HTTP APIs. If required credentials or resource IDs are missing, get them from the environment, the user, Mosoo UI, or Mosoo CLI when it is available. Do not guess or synthesize Mosoo IDs.

Resource IDs in v1 are bare ULIDs, not prefixed IDs.

Authentication and access

All API requests require an API token:

Authorization: Bearer mst_...

JSON requests also require:

Content-Type: application/json

A valid request must pass all of these checks:

1. The Agent exists.
2. The Agent is published and has API access enabled.
3. The API token is valid and not revoked.
4. The Agent has a live API endpoint version.
5. The API token owner owns the App that owns the Agent.
6. The requested Thread or file is visible to the API token owner.

The API token does not switch users, create a multi-user access context, or let a request override model provider, channel, tool, or runtime settings. Configure and publish the Agent in Mosoo before calling the API.

Responsibility boundary

Quick start workflow

Use this workflow when implementing the quickstart in application code. It is based on the human quickstart, but it starts after the Agent already exists, is published, and has API access enabled.

Implementation rules:

• Build the app-side integration layer around the published Mosoo Agent running in Mosoo's sandbox; do not implement a local Agent runtime or replacement sandbox.
• Do not call model providers directly for this Mosoo Agent integration.
• Do not send provider credentials, model configuration, channel credentials, tool configuration, or Agent configuration through this public API.
• Use Idempotency-Key for Thread creation and event submission.
• Treat Thread events as the integration contract and GET /threads/{threadId}/events as the stable source for results.
• Keep Agent creation, App management, and Agent lifecycle operations outside this workflow.
• On failure, branch on error.code and follow the error handling table below.

Minimal call sequence

Set credentials:

export MOSOO_API_TOKEN="mst_..."
export MOSOO_AGENT_ID="01J00000000000000000000001"

Create a Thread and queue the initial Run:

curl -X POST "https://try.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."
        }
      ]
    }
  }'

Store thread.id:

export MOSOO_THREAD_ID="01J00000000000000000000002"

Send a follow-up message:

curl -X POST "https://try.mosoo.ai/api/v1/threads/$MOSOO_THREAD_ID/events" \
  -H "Authorization: Bearer $MOSOO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ticket-182-follow-up-1" \
  -d '{
    "events": [
      {
        "type": "user_message",
        "clientRequestId": "ticket-182-message-1",
        "text": "Give me the three highest-priority next actions."
      }
    ]
  }'

Read the public event log:

curl "https://try.mosoo.ai/api/v1/threads/$MOSOO_THREAD_ID/events?limit=100" \
  -H "Authorization: Bearer $MOSOO_API_TOKEN"

File upload flow

Use this flow when a Thread or user message needs a file attachment. Uploads are scoped to the Agent API Endpoint App, so the file can be uploaded before the Thread exists. Public uploads use multipart/form-data and accept files up to 67108864 bytes.

Upload the file:

printf 'Customer asks for an implementation plan.' > brief.txt

curl -X POST "https://try.mosoo.ai/api/v1/agents/$MOSOO_AGENT_ID/files" \
  -H "Authorization: Bearer $MOSOO_API_TOKEN" \
  -F "file=@brief.txt;type=text/plain"

The response is a PublicFileResponse. Store file.id.

export MOSOO_FILE_ID="01J0000000000000000000000J"

Use the file in the first user message by adding top-level resources to the create-Thread request:

curl -X POST "https://try.mosoo.ai/api/v1/agents/$MOSOO_AGENT_ID/threads" \
  -H "Authorization: Bearer $MOSOO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "client_external_ref": "ticket-182",
    "resources": [
      {
        "type": "file",
        "file_id": "01J0000000000000000000000J"
      }
    ],
    "input": {
      "type": "user.message",
      "content": [
        {
          "type": "text",
          "text": "Summarize the attached file."
        }
      ]
    }
  }'

Use the file in a later user message with event-level resources:

curl -X POST "https://try.mosoo.ai/api/v1/threads/$MOSOO_THREAD_ID/events" \
  -H "Authorization: Bearer $MOSOO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ticket-182-file-question-1" \
  -d '{
    "events": [
      {
        "type": "user_message",
        "resources": [
          {
            "type": "file",
            "file_id": "01J0000000000000000000000J"
          }
        ],
        "text": "Summarize the attached file."
      }
    ]
  }'

After a file is mounted into a Thread, GET /threads/{threadId}/files lists it and GET /files/{fileId}/content downloads its bytes when visible to the API token caller.

Idempotency

Idempotency-Key is supported on:

• POST /agents/{agentId}/threads
• POST /threads/{threadId}/events

Rules:

• The key is scoped to the API token, method, route, and request body.
• Reusing the same key with the same request replays the stored response.
• Reusing the same key with a different request returns 409 idempotency_conflict.
• Reusing the key while the first request is still processing returns 409 idempotency_conflict.
• Keys must be non-empty and 128 characters or fewer.
• Conflict responses can include Retry-After.

Generate stable keys from your own operation IDs, such as ticket-182-create-thread or job-2026-06-23-run-1-message-3.

Reading results

The stable read surface is the Thread event log.

Use GET /threads/{threadId}/events for polling and snapshots. Use GET /threads/{threadId}/events/stream for long-running consumer UX.

Do not expect event APIs to expose raw runtime payloads, private transcripts, or internal diagnostics. Each event entry has public fields:

Important event types:

• user.message
• agent.message.delta
• agent.thinking.delta
• tool.confirmation.required
• tool.use.started
• tool.use.completed
• file.changed
• session_files.updated
• run.started
• run.completed
• run.failed
• session.status
• usage.updated

Status values

Thread status:

Run status:

Error handling

All non-2xx public API JSON errors use this envelope:

{
  "error": {
    "code": "invalid_request",
    "message": "Request body must be an object."
  }
}

Branch on error.code, not error.message. The message is for developers and should not be displayed directly to end users.

Retry policy:

• Safe to retry with the same Idempotency-Key: network timeouts, 5xx from create-thread or send-events, and idempotency_conflict caused by in-flight processing.
• Safe to retry after delay: rate_limited, using Retry-After.
• Do not retry unchanged: invalid_request, invalid_json, unauthenticated, forbidden, not_found, agent_not_published, service_inactive, readiness_blocked.

API contract

This section is generated from /docs/openapi/mosoo-openapi.en.generated.json. Do not edit it manually; run npm run openapi:sync.

All endpoints below are relative to /api/v1.

Common error response envelope:

{
  "error": {
    "code": "invalid_request",
    "message": "Request body must be an object."
  }
}

POST /agents/{agentId}/threads

Purpose: Creates a Thread and the backing AgentSession. If input is present, Mosoo also queues the initial Run. If input is omitted, the Thread is immediately visible with IDLE status and no run. API token requests are attributed to the current Mosoo user.

Path params:

• agentId required, string(ulid). Agent API Endpoint ID from the Agent's API Access panel. v1 IDs are bare ULIDs.

Headers:

• Idempotency-Key optional, string. Optional key for retry-safe create-thread and send-events calls. Reusing the same key with the same request returns the original response. Reusing the key while the original request is still processing returns 409.

Request body:

• application/json: CreateThreadRequest

Example emptyThread:

{
  "client_external_ref": "draft-empty-thread"
}

Example accessTokenWithFile:

{
  "client_external_ref": "linear-ENG-123",
  "input": {
    "content": [
      {
        "text": "Summarize the attached launch plan and list follow-ups.",
        "type": "text"
      }
    ],
    "type": "user.message"
  },
  "resources": [
    {
      "file_id": "01J0000000000000000000000J",
      "type": "file"
    }
  ]
}

Example accessTokenBasic:

{
  "client_external_ref": "demo-thread-001",
  "input": {
    "content": [
      {
        "text": "Say hello from the API.",
        "type": "text"
      }
    ],
    "type": "user.message"
  }
}

Example cattleAgentSameShape:

{
  "input": {
    "content": [
      {
        "text": "Run this one-off Public Thread API request.",
        "type": "text"
      }
    ],
    "type": "user.message"
  }
}

Success responses:

• 201: Created Thread. (application/json -> CreateThreadResponse)

Error responses:

• 400 InvalidRequest: The request shape or query value is invalid.
• 401 Unauthenticated: A valid API token is required.
• 403 Forbidden: This operation is not allowed for this Agent.
• 404 NotFound: The resource was not found in the current Mosoo workspace.
• 409 Conflict: The Agent/session state rejects this action, or an Idempotency-Key is already processing or was reused for a different request.
• 429 RateLimited: The API token exceeded the public API request budget for the current window.
• 500 InternalError: The request failed unexpectedly.

GET /agents/{agentId}/threads

Purpose: Returns Threads created by the authenticated API token.

Path params:

• agentId required, string(ulid). Agent API Endpoint ID from the Agent's API Access panel. v1 IDs are bare ULIDs.

Query params:

• archived optional, boolean. Filter by archived state: true returns only archived Threads, false only active ones. Omit to return all Threads.

Success responses:

• 200: Thread list. (application/json -> object)

Error responses:

• 400 InvalidRequest: The request shape or query value is invalid.
• 401 Unauthenticated: A valid API token is required.
• 403 Forbidden: This operation is not allowed for this Agent.
• 404 NotFound: The resource was not found in the current Mosoo workspace.
• 409 Conflict: The Agent/session state rejects this action, or an Idempotency-Key is already processing or was reused for a different request.
• 429 RateLimited: The API token exceeded the public API request budget for the current window.
• 500 InternalError: The request failed unexpectedly.

GET /threads/{threadId}

Purpose: Returns the current Thread summary, its most recent Run, and links.

Path params:

• threadId required, string(ulid). Thread ID returned by create thread. v1 IDs are bare ULIDs.

Success responses:

• 200: Thread summary. (application/json -> RetrieveThreadResponse)

Error responses:

• 400 InvalidRequest: The request shape or query value is invalid.
• 401 Unauthenticated: A valid API token is required.
• 403 Forbidden: This operation is not allowed for this Agent.
• 404 NotFound: The resource was not found in the current Mosoo workspace.
• 409 Conflict: The Agent/session state rejects this action, or an Idempotency-Key is already processing or was reused for a different request.
• 429 RateLimited: The API token exceeded the public API request budget for the current window.
• 500 InternalError: The request failed unexpectedly.

POST /threads/{threadId}/events

Purpose: Applies a batch of events to the Thread: send user messages, answer pending permission requests, or interrupt the current Run. A user message queues a new Run when the Thread is idle.

Path params:

• threadId required, string(ulid). Thread ID returned by create thread. v1 IDs are bare ULIDs.

Headers:

• Idempotency-Key optional, string. Optional key for retry-safe create-thread and send-events calls. Reusing the same key with the same request returns the original response. Reusing the key while the original request is still processing returns 409.

Request body:

• application/json: SendEventsRequest

Example:

{
  "events": [
    {
      "text": "Say hello from the API.",
      "type": "user_message"
    }
  ]
}

Success responses:

• 200: Accepted event batch. (application/json -> SendEventsResponse)

Error responses:

• 400 InvalidRequest: The request shape or query value is invalid.
• 401 Unauthenticated: A valid API token is required.
• 403 Forbidden: This operation is not allowed for this Agent.
• 404 NotFound: The resource was not found in the current Mosoo workspace.
• 409 Conflict: The Agent/session state rejects this action, or an Idempotency-Key is already processing or was reused for a different request.
• 429 RateLimited: The API token exceeded the public API request budget for the current window.
• 500 InternalError: The request failed unexpectedly.

GET /threads/{threadId}/events

Purpose: Returns the latest public event log entries for this Thread in chronological order. If older public entries are omitted because the limit was reached, truncated is true. Event IDs are stable, so callers can retry or poll without treating the same ID as a new event. This is the stable snapshot read surface for CLI and API consumers; it does not expose raw runtime payloads, transcript, or diagnostics.

Path params:

• threadId required, string(ulid). Thread ID returned by create thread. v1 IDs are bare ULIDs.

Query params:

• limit optional, integer. Maximum number of latest Thread events to return.

Success responses:

• 200: Thread event list. (application/json -> ThreadEventListResponse)

Error responses:

• 400 InvalidRequest: The request shape or query value is invalid.
• 401 Unauthenticated: A valid API token is required.
• 403 Forbidden: This operation is not allowed for this Agent.
• 404 NotFound: The resource was not found in the current Mosoo workspace.
• 409 Conflict: The Agent/session state rejects this action, or an Idempotency-Key is already processing or was reused for a different request.
• 429 RateLimited: The API token exceeded the public API request budget for the current window.
• 500 InternalError: The request failed unexpectedly.

GET /threads/{threadId}/events/stream

Purpose: Streams public Thread event log entries as Server-Sent Events. Each thread.event data payload uses the same ThreadEventLogEntry shape as GET /threads/{threadId}/events. Events are emitted by stable event ID and the stream suppresses duplicate IDs observed during polling. The stream is for long-running consumer UX and does not expose raw runtime payloads, internal diagnostics, or private transcripts.

Path params:

• threadId required, string(ulid). Thread ID returned by create thread. v1 IDs are bare ULIDs.

Query params:

• limit optional, integer. Maximum number of latest Thread events to return.

Success responses:

• 200: Thread event stream. (text/event-stream -> string)

Example 200:

": connected\n\nevent: thread.event\nid: 01J00000000000000000000010\ndata: {\"id\":\"01J00000000000000000000010\",\"runId\":\"01J0000000000000000000000A\",\"type\":\"run.started\",\"status\":\"available\",\"content\":\"01J0000000000000000000000A\",\"occurredAt\":\"2026-05-19T00:00:01.000Z\",\"durationMs\":null,\"tokens\":null}\n\n"

Error responses:

• 400 InvalidRequest: The request shape or query value is invalid.
• 401 Unauthenticated: A valid API token is required.
• 403 Forbidden: This operation is not allowed for this Agent.
• 404 NotFound: The resource was not found in the current Mosoo workspace.
• 409 Conflict: The Agent/session state rejects this action, or an Idempotency-Key is already processing or was reused for a different request.
• 429 RateLimited: The API token exceeded the public API request budget for the current window.
• 500 InternalError: The request failed unexpectedly.

POST /agents/{agentId}/files

Purpose: Uploads a file into the Agent API Endpoint's App draft scope before a Thread exists. Use the returned file ID in create-thread or send-events resources.

Path params:

• agentId required, string(ulid). Agent API Endpoint ID from the Agent's API Access panel. v1 IDs are bare ULIDs.

Request body:

• multipart/form-data: object

Success responses:

• 201: Uploaded file. (application/json -> PublicFileResponse)

Example 201:

{
  "file": {
    "createdAt": "2026-05-19T00:02:00.000Z",
    "id": "01J0000000000000000000000J",
    "mimeType": "text/plain",
    "name": "brief.txt",
    "size": 19
  }
}

Error responses:

• 400 InvalidRequest: The request shape or query value is invalid.
• 401 Unauthenticated: A valid API token is required.
• 403 Forbidden: This operation is not allowed for this Agent.
• 404 NotFound: The resource was not found in the current Mosoo workspace.
• 409 Conflict: The Agent/session state rejects this action, or an Idempotency-Key is already processing or was reused for a different request.
• 429 RateLimited: The API token exceeded the public API request budget for the current window.
• 500 InternalError: The request failed unexpectedly.

GET /files/{fileId}

Purpose: Returns public file metadata for a pre-Thread uploaded file or a file attached to a public Thread visible to the API token.

Path params:

• fileId required, string(ulid). File ID returned by add or list Thread files. v1 IDs are bare ULIDs.

Success responses:

• 200: File metadata. (application/json -> PublicFileResponse)

Example 200:

{
  "file": {
    "createdAt": "2026-05-19T00:02:00.000Z",
    "id": "01J0000000000000000000000J",
    "mimeType": "text/plain",
    "name": "brief.txt",
    "size": 19
  }
}

Error responses:

• 400 InvalidRequest: The request shape or query value is invalid.
• 401 Unauthenticated: A valid API token is required.
• 403 Forbidden: This operation is not allowed for this Agent.
• 404 NotFound: The resource was not found in the current Mosoo workspace.
• 409 Conflict: The Agent/session state rejects this action, or an Idempotency-Key is already processing or was reused for a different request.
• 429 RateLimited: The API token exceeded the public API request budget for the current window.
• 500 InternalError: The request failed unexpectedly.

GET /threads/{threadId}/files

Purpose: Lists files attached to the Thread, including caller attachments and Agent artifacts.

Path params:

• threadId required, string(ulid). Thread ID returned by create thread. v1 IDs are bare ULIDs.

Success responses:

• 200: Thread file list. (application/json -> ThreadFileListResponse)

Example 200:

{
  "files": [
    {
      "committed": true,
      "createdAt": "2026-05-19T00:02:00.000Z",
      "id": "01J0000000000000000000000J",
      "kind": "attachment",
      "mimeType": "text/plain",
      "name": "brief.txt",
      "size": 19
    }
  ]
}

Error responses:

• 400 InvalidRequest: The request shape or query value is invalid.
• 401 Unauthenticated: A valid API token is required.
• 403 Forbidden: This operation is not allowed for this Agent.
• 404 NotFound: The resource was not found in the current Mosoo workspace.
• 409 Conflict: The Agent/session state rejects this action, or an Idempotency-Key is already processing or was reused for a different request.
• 429 RateLimited: The API token exceeded the public API request budget for the current window.
• 500 InternalError: The request failed unexpectedly.

GET /files/{fileId}/content

Purpose: Downloads bytes for a ready Thread attachment or Agent artifact. The file must belong to a public Thread visible to the API token.

Path params:

• fileId required, string(ulid). File ID returned by add or list Thread files. v1 IDs are bare ULIDs.

Query params:

• disposition optional, "attachment" | "inline". Controls the Content-Disposition response header. Use attachment for downloads or inline for previewable content.

Success responses:

• 200: Thread file content. (application/octet-stream -> string(binary))

Error responses:

• 400 InvalidRequest: The request shape or query value is invalid.
• 401 Unauthenticated: A valid API token is required.
• 403 Forbidden: This operation is not allowed for this Agent.
• 404 NotFound: The resource was not found in the current Mosoo workspace.
• 409 Conflict: The Agent/session state rejects this action, or an Idempotency-Key is already processing or was reused for a different request.
• 429 RateLimited: The API token exceeded the public API request budget for the current window.
• 500 InternalError: The request failed unexpectedly.

DELETE /files/{fileId}

Purpose: Deletes a pre-Thread uploaded file or a file attached to a public Thread visible to the API token.

Path params:

• fileId required, string(ulid). File ID returned by add or list Thread files. v1 IDs are bare ULIDs.

Success responses:

• 200: Deleted. (application/json -> object)

Error responses:

• 400 InvalidRequest: The request shape or query value is invalid.
• 401 Unauthenticated: A valid API token is required.
• 403 Forbidden: This operation is not allowed for this Agent.
• 404 NotFound: The resource was not found in the current Mosoo workspace.
• 409 Conflict: The Agent/session state rejects this action, or an Idempotency-Key is already processing or was reused for a different request.
• 429 RateLimited: The API token exceeded the public API request budget for the current window.
• 500 InternalError: The request failed unexpectedly.

DELETE /threads/{threadId}/files/{fileId}

Purpose: Detaches a file from the Thread.

Path params:

• threadId required, string(ulid). Thread ID returned by create thread. v1 IDs are bare ULIDs.
• fileId required, string(ulid). File ID returned by add or list Thread files. v1 IDs are bare ULIDs.

Success responses:

• 200: Removed. (application/json -> object)

Error responses:

• 400 InvalidRequest: The request shape or query value is invalid.
• 401 Unauthenticated: A valid API token is required.
• 403 Forbidden: This operation is not allowed for this Agent.
• 404 NotFound: The resource was not found in the current Mosoo workspace.
• 409 Conflict: The Agent/session state rejects this action, or an Idempotency-Key is already processing or was reused for a different request.
• 429 RateLimited: The API token exceeded the public API request budget for the current window.
• 500 InternalError: The request failed unexpectedly.

POST /threads/{threadId}/archive

Purpose: Archives the Thread so it is hidden from default Thread lists.

Path params:

• threadId required, string(ulid). Thread ID returned by create thread. v1 IDs are bare ULIDs.

Success responses:

• 200: Archived. (application/json -> object)

Error responses:

• 400 InvalidRequest: The request shape or query value is invalid.
• 401 Unauthenticated: A valid API token is required.
• 403 Forbidden: This operation is not allowed for this Agent.
• 404 NotFound: The resource was not found in the current Mosoo workspace.
• 409 Conflict: The Agent/session state rejects this action, or an Idempotency-Key is already processing or was reused for a different request.
• 429 RateLimited: The API token exceeded the public API request budget for the current window.
• 500 InternalError: The request failed unexpectedly.

POST /threads/{threadId}/unarchive

Purpose: Restores a previously archived Thread to active Thread lists.

Path params:

• threadId required, string(ulid). Thread ID returned by create thread. v1 IDs are bare ULIDs.

Success responses:

• 200: Unarchived. (application/json -> object)

Error responses:

• 400 InvalidRequest: The request shape or query value is invalid.
• 401 Unauthenticated: A valid API token is required.
• 403 Forbidden: This operation is not allowed for this Agent.
• 404 NotFound: The resource was not found in the current Mosoo workspace.
• 409 Conflict: The Agent/session state rejects this action, or an Idempotency-Key is already processing or was reused for a different request.
• 429 RateLimited: The API token exceeded the public API request budget for the current window.
• 500 InternalError: The request failed unexpectedly.

DELETE /threads/{threadId}

Purpose: Permanently deletes the Thread and its backing AgentSession.

Path params:

• threadId required, string(ulid). Thread ID returned by create thread. v1 IDs are bare ULIDs.

Success responses:

• 200: Deleted. (application/json -> object)

Error responses:

• 400 InvalidRequest: The request shape or query value is invalid.
• 401 Unauthenticated: A valid API token is required.
• 403 Forbidden: This operation is not allowed for this Agent.
• 404 NotFound: The resource was not found in the current Mosoo workspace.
• 409 Conflict: The Agent/session state rejects this action, or an Idempotency-Key is already processing or was reused for a different request.
• 429 RateLimited: The API token exceeded the public API request budget for the current window.
• 500 InternalError: The request failed unexpectedly.

Schema quick reference

ThreadEventInput

A single event posted to a Thread. Exactly one variant applies: send a user message, answer a pending permission request, or interrupt a running Run.

Variants:

1. object: Send a new user message into the Thread, optionally with file attachments.

   • resources optional, FileResource[]. Files to attach to this message. Each file must be a ready draft file uploaded through the Agent file endpoint by the same API token.
   • clientRequestId optional, string | null. Optional caller-supplied correlation ID echoed back on the matching event result so you can pair responses with the message you sent.
   • text required, string. The user message text. Must not be empty.
   • type required, "user_message". Discriminator selecting the send-user-message variant.

2. object: Answer a permission request the Agent raised while waiting for input (for example a tool confirmation).

   • decision required, "allow_once" | "reject_once". Whether to allow or reject the requested action for this single occurrence. allow_once permits it now; reject_once denies it now.
   • requestId required, string. ID of the permission request being answered, taken from the corresponding tool.confirmation.required event.
   • type required, "permission_decision". Discriminator selecting the permission-decision variant.

3. object: Interrupt a Run that is currently executing on the Thread.

   • runId optional, string(ulid) | null. Run ID (bare ULID) to interrupt. Omit or send null to interrupt the Thread's current Run.
   • type required, "user_interrupt". Discriminator selecting the interrupt variant.

SendEventsRequest

Request body for posting a batch of events to a Thread.

Fields:

• events required, ThreadEventInput[]. Ordered list of events to apply to the Thread. At least one is required.

FileResource

A file resource to mount into a Thread or user message.

Fields:

• file_id required, string(ulid). ID of a ready draft file uploaded through the Agent file endpoint.
• type required, "file". Resource discriminator. Only file is supported today.

PublicFile

Public file metadata.

Fields:

• createdAt required, string(date-time). Timestamp (RFC 3339) at which the file record was created.
• id required, string(ulid). File ID (bare ULID).
• mimeType required, string | null. Detected MIME type of the file, or null when unknown.
• name required, string. Original file name.
• size required, integer. File size in bytes.

PublicFileResponse

A single public file.

Fields:

• file required, PublicFile. Public file metadata.

ErrorResponse

Standard error envelope returned for any non-2xx public API response.

Fields:

• error required, object. Details about why the request failed.
  • code required, "agent_not_published" | "forbidden" | "idempotency_conflict" | "internal_error" | "invalid_json" | "invalid_request" | "not_found" | "rate_limited" | "readiness_blocked" | "service_inactive" | "unauthenticated". Stable, machine-readable error code you can branch on.
  • message required, string. Human-readable explanation of the error. Not intended for end users.

SendEventsResponse

Result of accepting a batch of events posted to a Thread.

Fields:

• acceptedAt required, string(date-time). Timestamp (RFC 3339) at which the event batch was accepted for processing.
• events required, ThreadEventResult[]. Per-event outcomes, in the same order as the submitted events.
• thread required, ThreadSummary. The Thread state after applying the batch.
• warnings required, UserWarning[]. Non-fatal warnings raised while accepting the batch (for example a partially honored request). Empty when there are none.

ThreadEventLogEntry

A single public event log entry for a Thread. This is the stable read surface and never exposes raw runtime payloads, transcripts, or diagnostics.

Fields:

• content required, string. Public content of the event — typically a reference to the associated payload (such as a message ID) rather than the raw runtime data.
• durationMs required, integer | null. Wall-clock duration of the event in milliseconds, when applicable (for example a completed Run). Null when not measured.
• id required, string(ulid). Unique event ID (bare ULID), monotonically increasing in chronological order.
• occurredAt required, string(date-time). Timestamp (RFC 3339) at which the event occurred.
• runId required, string(ulid) | null. Run ID (bare ULID) associated with this event, or null when the event is not run-scoped. Use this to reconstruct output for one current Run without mixing earlier Thread output.
• status required, "available" | "error" | "unsupported". Delivery status of the event: available when the event is fully populated, error when it failed, unsupported when this event type cannot be rendered on the public surface.
• tokens required, integer | null. Token count associated with the event when applicable (for example model usage). Null when not measured.
• type required, "agent.message.delta" | "agent.thinking.delta" | "file.changed" | "run.completed" | "run.failed" | "run.started" | "session.status" | "session_files.updated" | "tool.confirmation.required" | "tool.use.completed" | "tool.use.started" | "usage.updated" | "user.message". Event type, such as run.started, run.completed, agent.message.delta, or tool.use.started.

ThreadEventListResponse

A page of the latest Thread event log entries in chronological order.

Fields:

• events required, ThreadEventLogEntry[]. The returned event log entries, oldest first within the requested window.
• truncated required, boolean. True when older events exist beyond the returned window because the requested limit was reached.

ThreadEventResult

Outcome of a single submitted event.

Fields:

• clientRequestId required, string | null. The clientRequestId echoed from the submitted user message, or null when none was provided or the event type does not carry one.
• run required, RunSummary | null. The Run created or affected by this event, or null when the event did not start or change a Run.
• type required, "permission_decision" | "user_interrupt" | "user_message". The kind of event this result corresponds to.

CreateThreadRequest

Request body for creating a Thread. All fields are optional: omit input to create an empty IDLE Thread, or include it to queue the initial Run.

Fields:

• client_external_ref optional, string. Optional client-owned reference (for example an external ticket key) stored on the Thread for correlation. Not unique and not validated by Mosoo.
• resources optional, FileResource[]. Files uploaded through the Agent file endpoint and mounted into the first Run.
• input optional, object. Initial user message that seeds the Thread and queues the first Run. Omit to create an empty Thread with no run.
  • content required, object[]. Ordered content parts that make up the initial message.
  • type required, "user.message". Discriminator for the initial input. Always user.message.

CreateThreadResponse

Result of creating a Thread.

Fields:

• links required, ThreadLinks. Convenience links for the created Thread.
• run required, RunSummary | null. The initial Run queued when input was provided, or null when an empty Thread was created.
• thread required, ThreadSummary. The created Thread.

RetrieveThreadResponse

Current state of a Thread.

Fields:

• links required, ThreadLinks. Convenience links for the Thread.
• run required, RunSummary | null. The Thread's most recent Run, or null when no Run has been created yet.
• thread required, ThreadSummary. The Thread summary.

ThreadFile

A file associated with a Thread.

Fields:

• committed required, boolean. True once the file is durably attached to the Thread; false while it is still a draft handle.
• createdAt required, string(date-time). Timestamp (RFC 3339) at which the file was created.
• id required, string(ulid). Unique file ID (bare ULID).
• kind required, "attachment" | "artifact". Files added through the public API are attachments; artifacts are files produced by the Agent.
• mimeType required, string | null. Detected MIME type of the file, or null when unknown.
• name required, string. Original file name.
• size required, integer. File size in bytes.

ThreadFileListResponse

List of files attached to a Thread.

Fields:

• files required, ThreadFile[]. The Thread's files.

ThreadFileResponse

A single Thread file.

Fields:

• file required, ThreadFile. The Thread file metadata, including its identifier, name, MIME type, and origin.

ThreadAttributedUser

The account a Thread is attributed to (the current Mosoo user).

Fields:

• id required, string(ulid). Account ID (bare ULID) the Thread is attributed to.

ThreadCaller

The credential that created the Thread.

Fields:

• id required, string(ulid). ID (bare ULID) of the caller that created the Thread.
• kind required, "access_token". Caller credential type. access_token identifies an API token.

ThreadLinks

Convenience links for a Thread.

Fields:

• thread required, string. Absolute API URL of the Thread resource.

ThreadSummary

Summary of a Thread on a Agent API Endpoint.

Fields:

• agent_id required, string(ulid). ID (bare ULID) of the Agent API Endpoint this Thread belongs to.
• attributed_user required, ThreadAttributedUser | null. The account the Thread is attributed to, or null when not attributed to an account.
• client_external_ref required, string | null. The client-owned reference supplied at creation, or null when none was provided.
• created_at required, string(date-time). Timestamp (RFC 3339) at which the Thread was created.
• created_by required, ThreadCaller. The credential that created the Thread.
• id required, string(ulid). Unique Thread ID (bare ULID).
• kind required, "pet" | "cattle". Agent kind backing this Thread (for example a persistent or one-off Agent API Endpoint).
• last_run_id required, string(ulid) | null. ID (bare ULID) of the most recent Run, or null when no Run exists yet.
• source required, "api". Origin of the Thread. Always api for Threads created via this API.
• status required, "IDLE" | "RUNNING" | "RESCHEDULING" | "TERMINATED". Lifecycle status of the Thread: IDLE (no active run), RUNNING (a Run is executing), RESCHEDULING (between runs), or TERMINATED (ended).
• title required, string | null. Human-readable Thread title, or null when one has not been derived yet.
• updated_at required, string(date-time). Timestamp (RFC 3339) of the most recent change to the Thread.

RunSummary

Summary of a single Agent Run on a Thread.

Fields:

• completedAt required, string | null(date-time). Timestamp (RFC 3339) at which the Run reached a terminal state, or null while it has not finished.
• createdAt required, string(date-time). Timestamp (RFC 3339) at which the Run was created.
• error required, RunError | null. Structured failure summary when status is failed; null for successful, active, cancelled, or expired Runs.
• finalOutput required, RunFinalOutput | null. Stable final answer for a completed Run. Mosoo builds this from that Run's public agent.message.delta events in chronological order. Null until the Run status is completed.
• id required, string(ulid). Unique Run ID (bare ULID).
• startedAt required, string | null(date-time). Timestamp (RFC 3339) at which the Run began executing, or null while it is still queued.
• status required, "queued" | "booting" | "running" | "waiting_input" | "completed" | "failed" | "cancelled" | "expired". Current Run status. queued and booting precede execution; running and waiting_input are active; completed, failed, cancelled, expired are terminal.
• trigger required, "user_prompt" | "retry" | "resume" | "system". What started the Run: user_prompt (a user message), retry, resume, or system.
• updatedAt required, string(date-time). Timestamp (RFC 3339) of the most recent change to the Run.

RunError

Public-safe Run failure summary exposed on failed public Runs.

Fields:

• code required, string. Stable, machine-readable failure code.
• message required, string. Human-readable failure summary.
• retryable required, boolean. Whether retrying the Run may succeed without changing input.

RunFinalOutput

Final assistant answer for a completed public Thread Run.

Fields:

• text required, string. Text reconstructed from the current Run's public agent.message.delta events in chronological order.

UserWarning

A non-fatal warning surfaced to the caller.

Fields:

• code required, string. Stable, machine-readable warning code.
• message required, string. Human-readable explanation of the warning.

Implementation guardrails for coding agents

• Always send Authorization: Bearer $MOSOO_API_TOKEN.
• Always treat agentId, threadId, fileId, and runId as bare ULIDs.
• Use Idempotency-Key for create-thread and send-events retries.
• Use event log APIs as the source for public results.
• Do not assume raw model output, private runtime payloads, or internal diagnostics are exposed.
• Do not send provider credentials, model configuration, channel credentials, or Agent configuration through this public API.
• Do not retry invalid requests unchanged.
• Do not treat 403 as an authentication problem; 403 means the token was understood but the operation is not allowed for that resource.
• Do not treat a published Agent as ready unless create-thread succeeds or the user confirms Agent readiness in Mosoo.
• Prefer stable caller-owned references such as client_external_ref and clientRequestId for correlation.