{"components":{"responses":{"Conflict":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"The Agent/session state rejects this action, or an Idempotency-Key is already processing or was reused for a different request."},"Forbidden":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"The caller cannot consume this Agent."},"InternalError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"The request failed unexpectedly."},"InvalidRequest":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"The request shape or query value is invalid."},"NotFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"The resource was not found for this caller."},"RateLimited":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"The caller token exceeded the public API request budget for the current window.","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"minimum":1,"type":"integer"}}}},"Unauthenticated":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"A valid Access Token is required."}},"schemas":{"ThreadEventInput":{"description":"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.","oneOf":[{"additionalProperties":false,"description":"Send a new user message into the Thread, optionally with file attachments.","properties":{"resources":{"description":"Files to attach to this message. Each file must be a ready draft file uploaded through the Agent file endpoint by the same Access Token caller.","items":{"$ref":"#/components/schemas/FileResource"},"type":"array"},"requestId":{"description":"Optional caller-supplied request ID echoed back on the matching event result so you can pair responses with the message you sent.","type":["string","null"]},"text":{"description":"The user message text. Must not be empty.","minLength":1,"type":"string"},"type":{"const":"user_message","description":"Discriminator selecting the send-user-message variant."}},"required":["type","text"],"type":"object"},{"additionalProperties":false,"description":"Answer a permission request the Agent raised while waiting for input (for example a tool confirmation).","properties":{"decision":{"description":"Whether to allow or reject the requested action for this single occurrence. `allow_once` permits it now; `reject_once` denies it now.","enum":["allow_once","reject_once"]},"requestId":{"description":"ID of the permission request being answered, taken from the corresponding `tool.confirmation.required` event.","minLength":1,"type":"string"},"type":{"const":"permission_decision","description":"Discriminator selecting the permission-decision variant."}},"required":["type","requestId","decision"],"type":"object"},{"additionalProperties":false,"description":"Interrupt a Run that is currently executing on the Thread.","properties":{"runId":{"description":"Run ID (bare ULID) to interrupt. Omit or send null to interrupt the Thread's current Run.","oneOf":[{"example":"01ARZ3NDEKTSV4RRFFQ69G5FAV","format":"ulid","pattern":"^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$","type":"string"},{"type":"null"}]},"type":{"const":"user_interrupt","description":"Discriminator selecting the interrupt variant."}},"required":["type"],"type":"object"}]},"SendEventsRequest":{"additionalProperties":false,"description":"Request body for posting a batch of events to a Thread.","properties":{"events":{"description":"Ordered list of events to apply to the Thread. At least one is required.","items":{"$ref":"#/components/schemas/ThreadEventInput"},"minItems":1,"type":"array"}},"required":["events"],"type":"object"},"FileResource":{"additionalProperties":false,"description":"A file resource to mount into a Thread or user message.","properties":{"file_id":{"example":"01ARZ3NDEKTSV4RRFFQ69G5FAV","format":"ulid","pattern":"^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$","type":"string","maxLength":26,"minLength":1,"description":"ID of a ready draft file uploaded through the Agent file endpoint."},"type":{"const":"file","description":"Resource discriminator. Only `file` is supported today."}},"required":["type","file_id"],"type":"object"},"PublicFile":{"additionalProperties":false,"description":"Public file metadata.","properties":{"createdAt":{"description":"Timestamp (RFC 3339) at which the file record was created.","format":"date-time","type":"string"},"id":{"example":"01ARZ3NDEKTSV4RRFFQ69G5FAV","format":"ulid","pattern":"^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$","type":"string","maxLength":26,"minLength":1,"description":"File ID (bare ULID)."},"mimeType":{"description":"Detected MIME type of the file, or null when unknown.","type":["string","null"]},"name":{"description":"Original file name.","type":"string"},"size":{"description":"File size in bytes.","minimum":0,"type":"integer"}},"required":["createdAt","id","mimeType","name","size"],"type":"object"},"PublicFileResponse":{"additionalProperties":false,"description":"A single public file.","properties":{"file":{"$ref":"#/components/schemas/PublicFile","description":"Public file metadata."}},"required":["file"],"type":"object"},"ErrorResponse":{"description":"Standard error envelope returned for any non-2xx public API response.","properties":{"error":{"description":"Details about why the request failed.","properties":{"code":{"description":"Stable, machine-readable error code you can branch on.","enum":["agent_not_published","forbidden","idempotency_conflict","internal_error","invalid_json","invalid_request","not_found","rate_limited","readiness_blocked","service_inactive","unauthenticated"]},"message":{"description":"Human-readable explanation of the error. Not intended for end users.","type":"string"}},"required":["code","message"],"type":"object"}},"required":["error"],"type":"object"},"SendEventsResponse":{"additionalProperties":false,"description":"Result of accepting a batch of events posted to a Thread.","properties":{"acceptedAt":{"description":"Timestamp (RFC 3339) at which the event batch was accepted for processing.","format":"date-time","type":"string"},"events":{"description":"Per-event outcomes, in the same order as the submitted events.","items":{"$ref":"#/components/schemas/ThreadEventResult"},"type":"array"},"thread":{"$ref":"#/components/schemas/ThreadSummary","description":"The Thread state after applying the batch."},"warnings":{"description":"Non-fatal warnings raised while accepting the batch (for example a partially honored request). Empty when there are none.","items":{"$ref":"#/components/schemas/UserWarning"},"type":"array"}},"required":["acceptedAt","events","thread","warnings"],"type":"object"},"ThreadEventLogEntry":{"additionalProperties":false,"description":"A single public event log entry for a Thread. This is the stable read surface and never exposes raw runtime payloads, transcripts, or diagnostics.","properties":{"content":{"description":"Public content of the event — typically a reference to the associated payload (such as a message ID) rather than the raw runtime data.","type":"string"},"durationMs":{"description":"Wall-clock duration of the event in milliseconds, when applicable (for example a completed Run). Null when not measured.","type":["integer","null"]},"id":{"example":"01ARZ3NDEKTSV4RRFFQ69G5FAV","format":"ulid","pattern":"^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$","type":"string","description":"Unique event ID (bare ULID), monotonically increasing in chronological order."},"occurredAt":{"description":"Timestamp (RFC 3339) at which the event occurred.","format":"date-time","type":"string"},"runId":{"description":"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.","oneOf":[{"example":"01ARZ3NDEKTSV4RRFFQ69G5FAV","format":"ulid","pattern":"^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$","type":"string"},{"type":"null"}]},"status":{"description":"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.","enum":["available","error","unsupported"]},"toolCallId":{"description":"Opaque, durable ID shared by lifecycle events for one logical tool invocation. Use this value, not the event `id`, to correlate start, confirmation, and terminal events.","minLength":1,"type":"string"},"toolInput":{"additionalProperties":true,"description":"Structured tool arguments when this event carries a complete canonical input object.","type":"object"},"toolName":{"description":"Harness-neutral tool name when supplied by the runtime.","minLength":1,"type":"string"},"tokens":{"description":"Token count associated with the event when applicable (for example model usage). Null when not measured.","type":["integer","null"]},"type":{"description":"Event type, such as `run.started`, `run.completed`, `agent.message.delta`, or `tool.use.started`.","enum":["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"]}},"required":["content","durationMs","id","occurredAt","runId","status","tokens","type"],"type":"object"},"ThreadEventListResponse":{"additionalProperties":false,"description":"A page of the latest Thread event log entries in chronological order.","properties":{"events":{"description":"The returned event log entries, oldest first within the requested window.","items":{"$ref":"#/components/schemas/ThreadEventLogEntry"},"type":"array"},"truncated":{"description":"True when older events exist beyond the returned window because the requested limit was reached.","type":"boolean"}},"required":["events","truncated"],"type":"object"},"ThreadEventResult":{"additionalProperties":false,"description":"Outcome of a single submitted event.","properties":{"requestId":{"description":"The `requestId` echoed from the submitted user message, or null when none was provided or the event type does not carry one.","type":["string","null"]},"run":{"description":"The Run created or affected by this event, or null when the event did not start or change a Run.","oneOf":[{"$ref":"#/components/schemas/RunSummary"},{"type":"null"}]},"type":{"description":"The kind of event this result corresponds to.","enum":["permission_decision","user_interrupt","user_message"]}},"required":["requestId","run","type"],"type":"object"},"CreateThreadRequest":{"additionalProperties":false,"description":"Request body for creating a Thread. `userId` is required. Omit `input` to create an empty IDLE Thread, or include it to queue the initial Run.","properties":{"userId":{"description":"Opaque application-user identifier supplied by the trusted backend. It is immutable for the lifetime of the Thread and is delegated to MCP servers during Runs.","maxLength":255,"minLength":1,"type":"string"},"resources":{"description":"Files uploaded through the Agent file endpoint and mounted into the first Run.","items":{"$ref":"#/components/schemas/FileResource"},"type":"array"},"input":{"additionalProperties":false,"description":"Initial user message that seeds the Thread and queues the first Run. Omit to create an empty Thread with no run.","properties":{"content":{"description":"Ordered content parts that make up the initial message.","items":{"additionalProperties":false,"description":"A single content part of the initial message.","properties":{"text":{"description":"The text of this content part. Must not be empty.","maxLength":32000,"minLength":1,"type":"string"},"type":{"const":"text","description":"Content part discriminator. Only `text` is supported today."}},"required":["type","text"],"type":"object"},"minItems":1,"type":"array"},"type":{"const":"user.message","description":"Discriminator for the initial input. Always `user.message`."}},"required":["type","content"],"type":"object"}},"required":["userId"],"type":"object"},"CreateThreadResponse":{"additionalProperties":false,"description":"Result of creating a Thread.","properties":{"links":{"$ref":"#/components/schemas/ThreadLinks","description":"Convenience links for the created Thread."},"run":{"description":"The initial Run queued when `input` was provided, or null when an empty Thread was created.","oneOf":[{"$ref":"#/components/schemas/RunSummary"},{"type":"null"}]},"thread":{"$ref":"#/components/schemas/ThreadSummary","description":"The created Thread."}},"required":["links","run","thread"],"type":"object"},"RetrieveThreadResponse":{"additionalProperties":false,"description":"Current state of a Thread.","properties":{"links":{"$ref":"#/components/schemas/ThreadLinks","description":"Convenience links for the Thread."},"run":{"description":"The Thread's most recent Run, or null when no Run has been created yet.","oneOf":[{"$ref":"#/components/schemas/RunSummary"},{"type":"null"}]},"thread":{"$ref":"#/components/schemas/ThreadSummary","description":"The Thread summary."}},"required":["links","run","thread"],"type":"object"},"ThreadFile":{"additionalProperties":false,"description":"A file associated with a Thread.","properties":{"committed":{"description":"True once the file is durably attached to the Thread; false while it is still a draft handle.","type":"boolean"},"createdAt":{"description":"Timestamp (RFC 3339) at which the file was created.","format":"date-time","type":"string"},"id":{"example":"01ARZ3NDEKTSV4RRFFQ69G5FAV","format":"ulid","pattern":"^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$","type":"string","description":"Unique file ID (bare ULID)."},"kind":{"description":"Files added through the public API are attachments; artifacts are files produced by the Agent.","enum":["attachment","artifact"]},"mimeType":{"description":"Detected MIME type of the file, or null when unknown.","type":["string","null"]},"name":{"description":"Original file name.","type":"string"},"size":{"description":"File size in bytes.","minimum":0,"type":"integer"}},"required":["committed","createdAt","id","kind","mimeType","name","size"],"type":"object"},"ThreadFileListResponse":{"additionalProperties":false,"description":"List of files attached to a Thread.","properties":{"files":{"description":"The Thread's files.","items":{"$ref":"#/components/schemas/ThreadFile"},"type":"array"}},"required":["files"],"type":"object"},"ThreadFileResponse":{"additionalProperties":false,"description":"A single Thread file.","properties":{"file":{"$ref":"#/components/schemas/ThreadFile","description":"The Thread file metadata, including its identifier, name, MIME type, and origin."}},"required":["file"],"type":"object"},"ThreadLinks":{"additionalProperties":false,"description":"Convenience links for a Thread.","properties":{"thread":{"description":"Absolute API URL of the Thread resource.","type":"string"}},"required":["thread"],"type":"object"},"ThreadSummary":{"additionalProperties":false,"description":"Summary of a Thread on a Agent API Endpoint.","properties":{"agent_id":{"example":"01ARZ3NDEKTSV4RRFFQ69G5FAV","format":"ulid","pattern":"^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$","type":"string","description":"ID (bare ULID) of the Agent API Endpoint this Thread belongs to."},"created_at":{"description":"Timestamp (RFC 3339) at which the Thread was created.","format":"date-time","type":"string"},"id":{"example":"01ARZ3NDEKTSV4RRFFQ69G5FAV","format":"ulid","pattern":"^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$","type":"string","description":"Unique Thread ID (bare ULID)."},"kind":{"description":"Agent kind backing this Thread (for example a persistent or one-off Agent API Endpoint).","enum":["pet","cattle"]},"last_run_id":{"description":"ID (bare ULID) of the most recent Run, or null when no Run exists yet.","oneOf":[{"example":"01ARZ3NDEKTSV4RRFFQ69G5FAV","format":"ulid","pattern":"^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$","type":"string"},{"type":"null"}]},"source":{"const":"api","description":"Origin of the Thread. Always `api` for Threads created via this API."},"status":{"description":"Lifecycle status of the Thread: `IDLE` (no active run), `RUNNING` (a Run is executing), `RESCHEDULING` (between runs), or `TERMINATED` (ended).","enum":["IDLE","RUNNING","RESCHEDULING","TERMINATED"]},"title":{"description":"Human-readable Thread title, or null when one has not been derived yet.","type":["string","null"]},"updated_at":{"description":"Timestamp (RFC 3339) of the most recent change to the Thread.","format":"date-time","type":"string"},"userId":{"description":"Immutable opaque application-user identifier supplied when the Thread was created.","maxLength":255,"minLength":1,"type":"string"}},"required":["agent_id","created_at","id","kind","last_run_id","source","status","title","updated_at","userId"],"type":"object"},"RunSummary":{"additionalProperties":false,"description":"Summary of a single Agent Run on a Thread.","properties":{"completedAt":{"description":"Timestamp (RFC 3339) at which the Run reached a terminal state, or null while it has not finished.","format":"date-time","type":["string","null"]},"createdAt":{"description":"Timestamp (RFC 3339) at which the Run was created.","format":"date-time","type":"string"},"error":{"description":"Structured failure summary when status is `failed`; null for successful, active, cancelled, or expired Runs.","oneOf":[{"$ref":"#/components/schemas/RunError"},{"type":"null"}]},"finalOutput":{"description":"Public-safe canonical final assistant answer for a completed Run. It is derived from the persisted final assistant message, not reconstructed from public `agent.message.delta` events. Null until that final message is persisted or when the Run has no final assistant answer.","oneOf":[{"$ref":"#/components/schemas/RunFinalOutput"},{"type":"null"}]},"id":{"example":"01ARZ3NDEKTSV4RRFFQ69G5FAV","format":"ulid","pattern":"^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$","type":"string","description":"Unique Run ID (bare ULID)."},"startedAt":{"description":"Timestamp (RFC 3339) at which the Run began executing, or null while it is still queued.","format":"date-time","type":["string","null"]},"status":{"description":"Current Run status. `queued` and `booting` precede execution; `running` and `waiting_input` are active; `completed`, `failed`, `cancelled`, `expired` are terminal.","enum":["queued","booting","running","waiting_input","completed","failed","cancelled","expired"]},"trigger":{"description":"What started the Run: `user_prompt` (a user message), `retry`, `resume`, or `system`.","enum":["user_prompt","retry","resume","system"]},"updatedAt":{"description":"Timestamp (RFC 3339) of the most recent change to the Run.","format":"date-time","type":"string"}},"required":["completedAt","createdAt","error","finalOutput","id","startedAt","status","trigger","updatedAt"],"type":"object"},"RunError":{"additionalProperties":false,"description":"Public-safe Run failure summary exposed on failed public Runs.","properties":{"code":{"description":"Stable, machine-readable failure code.","minLength":1,"type":"string"},"message":{"description":"Human-readable failure summary.","minLength":1,"type":"string"},"retryable":{"description":"Whether retrying the Run may succeed without changing input.","type":"boolean"}},"required":["code","message","retryable"],"type":"object"},"RunFinalOutput":{"additionalProperties":false,"description":"Final assistant answer for a completed public Thread Run.","properties":{"text":{"description":"Public-safe text derived from the Run's persisted final assistant message. Provider-private control markup is omitted and reported through warnings.","type":"string"},"warnings":{"description":"Non-fatal warnings raised while making provider output safe for public consumption.","items":{"$ref":"#/components/schemas/RunFinalOutputWarning"},"type":"array"}},"required":["text"],"type":"object"},"RunFinalOutputWarning":{"additionalProperties":false,"description":"A non-fatal warning attached to canonical final output.","properties":{"code":{"const":"unresolved_provider_citation","description":"Stable code identifying provider citation markup that could not be resolved."},"count":{"description":"Number of private citation envelopes removed from the public text.","minimum":1,"type":"integer"}},"required":["code","count"],"type":"object"},"UserWarning":{"additionalProperties":false,"description":"A non-fatal warning surfaced to the caller.","properties":{"code":{"description":"Stable, machine-readable warning code.","type":"string"},"message":{"description":"Human-readable explanation of the warning.","type":"string"}},"required":["code","message"],"type":"object"}},"securitySchemes":{"accessToken":{"bearerFormat":"mosoo Access Token","description":"Use Authorization: Bearer mst_... . Access Tokens identify an account and do not carry scopes.","scheme":"bearer","type":"http"}}},"info":{"description":"Public HTTPS API for creating and retrieving Threads on mosoo Agent API Endpoints. v1 resource identifiers are bare ULIDs, not prefixed IDs. Access Tokens identify the account caller. Runtime execution resolves the Agent API Endpoint owner's capabilities while the Thread is attributed to the token owner.","title":"mosoo Public Thread API","version":"v1"},"openapi":"3.1.0","paths":{"/agents/{agentId}/files":{"post":{"description":"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.","parameters":[{"description":"Agent API Endpoint ID from the Agent's API Access panel. v1 IDs are bare ULIDs.","example":"01J00000000000000000000001","in":"path","name":"agentId","required":true,"schema":{"example":"01J00000000000000000000001","format":"ulid","pattern":"^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$","type":"string","x-default":"01J00000000000000000000001"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"additionalProperties":false,"properties":{"file":{"description":"File bytes to upload before attaching them to a Thread.","format":"binary","type":"string"}},"required":["file"],"type":"object"}}},"required":true},"security":[{"accessToken":[]}],"summary":"Upload an Agent file","responses":{"201":{"content":{"application/json":{"example":{"file":{"createdAt":"2026-05-19T00:02:00.000Z","id":"01J0000000000000000000000J","mimeType":"text/plain","name":"brief.txt","size":19}},"schema":{"$ref":"#/components/schemas/PublicFileResponse"}}},"description":"Uploaded file."},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/files/{fileId}/content":{"get":{"description":"Downloads bytes for a ready Thread attachment or Agent artifact. The file must belong to a public Thread visible to the Access Token caller.","parameters":[{"description":"File ID returned by add or list Thread files. v1 IDs are bare ULIDs.","example":"01J0000000000000000000000J","in":"path","name":"fileId","required":true,"schema":{"example":"01J0000000000000000000000J","format":"ulid","pattern":"^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$","type":"string","x-default":"01J0000000000000000000000J"}},{"description":"Controls the Content-Disposition response header. Use attachment for downloads or inline for previewable content.","example":"attachment","in":"query","name":"disposition","schema":{"default":"attachment","enum":["attachment","inline"],"type":"string"}}],"security":[{"accessToken":[]}],"summary":"Download Thread file content","responses":{"200":{"content":{"application/octet-stream":{"schema":{"format":"binary","type":"string"}}},"description":"Thread file content.","headers":{"Cache-Control":{"description":"Set to no-store for public API file downloads.","schema":{"type":"string"}},"Content-Disposition":{"description":"Download or inline content disposition for the returned file.","schema":{"type":"string"}},"Content-Length":{"description":"File size in bytes.","schema":{"minimum":0,"type":"integer"}},"ETag":{"description":"Storage ETag for the returned object.","schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/files/{fileId}":{"delete":{"description":"Deletes a pre-Thread uploaded file or a file attached to a public Thread visible to the Access Token caller.","parameters":[{"description":"File ID returned by add or list Thread files. v1 IDs are bare ULIDs.","example":"01J0000000000000000000000J","in":"path","name":"fileId","required":true,"schema":{"example":"01J0000000000000000000000J","format":"ulid","pattern":"^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$","type":"string","x-default":"01J0000000000000000000000J"}}],"security":[{"accessToken":[]}],"summary":"Delete a file","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"ok":{"const":true}},"required":["ok"],"type":"object"}}},"description":"Deleted."},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"get":{"description":"Returns public file metadata for a pre-Thread uploaded file or a file attached to a public Thread visible to the Access Token caller.","parameters":[{"description":"File ID returned by add or list Thread files. v1 IDs are bare ULIDs.","example":"01J0000000000000000000000J","in":"path","name":"fileId","required":true,"schema":{"example":"01J0000000000000000000000J","format":"ulid","pattern":"^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$","type":"string","x-default":"01J0000000000000000000000J"}}],"security":[{"accessToken":[]}],"summary":"Retrieve file metadata","responses":{"200":{"content":{"application/json":{"example":{"file":{"createdAt":"2026-05-19T00:02:00.000Z","id":"01J0000000000000000000000J","mimeType":"text/plain","name":"brief.txt","size":19}},"schema":{"$ref":"#/components/schemas/PublicFileResponse"}}},"description":"File metadata."},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/agents/{agentId}/threads":{"get":{"description":"Returns Threads created by the authenticated Access Token caller.","parameters":[{"description":"Agent API Endpoint ID from the Agent's API Access panel. v1 IDs are bare ULIDs.","example":"01J00000000000000000000001","in":"path","name":"agentId","required":true,"schema":{"example":"01J00000000000000000000001","format":"ulid","pattern":"^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$","type":"string","x-default":"01J00000000000000000000001"}},{"description":"Filter by archived state: true returns only archived Threads, false only active ones. Omit to return all Threads.","in":"query","name":"archived","schema":{"type":"boolean"}}],"security":[{"accessToken":[]}],"summary":"List Threads for an Agent API Endpoint","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"threads":{"items":{"$ref":"#/components/schemas/ThreadSummary"},"maxItems":100,"type":"array"}},"required":["threads"],"type":"object"}}},"description":"Thread list."},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"description":"Creates a Thread and the backing AgentSession for the required application `userId`. 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.","parameters":[{"description":"Agent API Endpoint ID from the Agent's API Access panel. v1 IDs are bare ULIDs.","example":"01J00000000000000000000001","in":"path","name":"agentId","required":true,"schema":{"example":"01J00000000000000000000001","format":"ulid","pattern":"^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$","type":"string","x-default":"01J00000000000000000000001"}},{"description":"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.","example":"thread-20260528-linear-eng-123","in":"header","name":"Idempotency-Key","schema":{"maxLength":128,"type":"string"}}],"requestBody":{"content":{"application/json":{"examples":{"emptyThread":{"summary":"Create an empty Thread","value":{"userId":"customer-123"}},"accessTokenWithFile":{"summary":"Access Token with an uploaded file","value":{"input":{"content":[{"text":"Summarize the attached launch plan and list follow-ups.","type":"text"}],"type":"user.message"},"resources":[{"file_id":"01J0000000000000000000000J","type":"file"}],"userId":"customer-123"}},"accessTokenBasic":{"summary":"Access Token","value":{"input":{"content":[{"text":"Say hello from the API.","type":"text"}],"type":"user.message"},"userId":"customer-123"}},"cattleAgentSameShape":{"summary":"Cattle Agent using the same request shape","value":{"input":{"content":[{"text":"Run this one-off Public Thread API request.","type":"text"}],"type":"user.message"},"userId":"automation"}}},"schema":{"$ref":"#/components/schemas/CreateThreadRequest"}}},"required":true},"summary":"Create a Thread for an Agent API Endpoint","responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateThreadResponse"}}},"description":"Created Thread.","headers":{"Idempotency-Replayed":{"description":"Present as true when this response is replayed from a previous completed request.","schema":{"const":"true","type":"string"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/threads/{threadId}":{"delete":{"description":"Permanently deletes the Thread and its backing AgentSession.","parameters":[{"description":"Thread ID returned by create thread. v1 IDs are bare ULIDs.","example":"01J00000000000000000000009","in":"path","name":"threadId","required":true,"schema":{"example":"01J00000000000000000000009","format":"ulid","pattern":"^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$","type":"string","x-default":"01J00000000000000000000009"}}],"security":[{"accessToken":[]}],"summary":"Delete a Thread","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"ok":{"const":true}},"required":["ok"],"type":"object"}}},"description":"Deleted."},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"get":{"description":"Returns the current Thread summary, its most recent Run, and links.","parameters":[{"description":"Thread ID returned by create thread. v1 IDs are bare ULIDs.","example":"01J00000000000000000000009","in":"path","name":"threadId","required":true,"schema":{"example":"01J00000000000000000000009","format":"ulid","pattern":"^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$","type":"string","x-default":"01J00000000000000000000009"}}],"summary":"Retrieve Thread summary","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetrieveThreadResponse"}}},"description":"Thread summary."},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/threads/{threadId}/archive":{"post":{"description":"Archives the Thread so it is hidden from default Thread lists.","parameters":[{"description":"Thread ID returned by create thread. v1 IDs are bare ULIDs.","example":"01J00000000000000000000009","in":"path","name":"threadId","required":true,"schema":{"example":"01J00000000000000000000009","format":"ulid","pattern":"^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$","type":"string","x-default":"01J00000000000000000000009"}}],"security":[{"accessToken":[]}],"summary":"Archive a Thread","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"ok":{"const":true}},"required":["ok"],"type":"object"}}},"description":"Archived."},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/threads/{threadId}/events":{"get":{"description":"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.","parameters":[{"description":"Thread ID returned by create thread. v1 IDs are bare ULIDs.","example":"01J00000000000000000000009","in":"path","name":"threadId","required":true,"schema":{"example":"01J00000000000000000000009","format":"ulid","pattern":"^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$","type":"string","x-default":"01J00000000000000000000009"}},{"description":"Maximum number of latest Thread events to return.","example":100,"in":"query","name":"limit","schema":{"default":100,"maximum":1000,"minimum":1,"type":"integer"}}],"summary":"List Thread events","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ThreadEventListResponse"}}},"description":"Thread event list."},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"description":"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.","parameters":[{"description":"Thread ID returned by create thread. v1 IDs are bare ULIDs.","example":"01J00000000000000000000009","in":"path","name":"threadId","required":true,"schema":{"example":"01J00000000000000000000009","format":"ulid","pattern":"^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$","type":"string","x-default":"01J00000000000000000000009"}},{"description":"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.","example":"thread-20260528-linear-eng-123","in":"header","name":"Idempotency-Key","schema":{"maxLength":128,"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendEventsRequest"},"example":{"events":[{"text":"Say hello from the API.","type":"user_message"}]}}},"required":true},"security":[{"accessToken":[]}],"summary":"Send user messages, permission decisions, or interrupts to a Thread","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendEventsResponse"}}},"description":"Accepted event batch.","headers":{"Idempotency-Replayed":{"description":"Present as true when this response is replayed from a previous completed request.","schema":{"const":"true","type":"string"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/threads/{threadId}/events/stream":{"get":{"description":"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.","parameters":[{"description":"Thread ID returned by create thread. v1 IDs are bare ULIDs.","example":"01J00000000000000000000009","in":"path","name":"threadId","required":true,"schema":{"example":"01J00000000000000000000009","format":"ulid","pattern":"^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$","type":"string","x-default":"01J00000000000000000000009"}},{"description":"Maximum number of latest Thread events to return.","example":100,"in":"query","name":"limit","schema":{"default":100,"maximum":1000,"minimum":1,"type":"integer"}}],"summary":"Stream Thread events","responses":{"200":{"content":{"text/event-stream":{"example":": 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","schema":{"type":"string"}}},"description":"Thread event stream."},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/threads/{threadId}/files":{"get":{"description":"Lists files attached to the Thread, including caller attachments and Agent artifacts.","parameters":[{"description":"Thread ID returned by create thread. v1 IDs are bare ULIDs.","example":"01J00000000000000000000009","in":"path","name":"threadId","required":true,"schema":{"example":"01J00000000000000000000009","format":"ulid","pattern":"^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$","type":"string","x-default":"01J00000000000000000000009"}}],"security":[{"accessToken":[]}],"summary":"List Thread files","responses":{"200":{"content":{"application/json":{"example":{"files":[{"committed":true,"createdAt":"2026-05-19T00:02:00.000Z","id":"01J0000000000000000000000J","kind":"attachment","mimeType":"text/plain","name":"brief.txt","size":19}]},"schema":{"$ref":"#/components/schemas/ThreadFileListResponse"}}},"description":"Thread file list."},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/threads/{threadId}/files/{fileId}":{"delete":{"description":"Detaches a file from the Thread.","parameters":[{"description":"Thread ID returned by create thread. v1 IDs are bare ULIDs.","example":"01J00000000000000000000009","in":"path","name":"threadId","required":true,"schema":{"example":"01J00000000000000000000009","format":"ulid","pattern":"^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$","type":"string","x-default":"01J00000000000000000000009"}},{"description":"File ID returned by add or list Thread files. v1 IDs are bare ULIDs.","example":"01J0000000000000000000000J","in":"path","name":"fileId","required":true,"schema":{"example":"01J0000000000000000000000J","format":"ulid","pattern":"^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$","type":"string","x-default":"01J0000000000000000000000J"}}],"security":[{"accessToken":[]}],"summary":"Remove a Thread file","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"ok":{"const":true}},"required":["ok"],"type":"object"}}},"description":"Removed."},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/threads/{threadId}/unarchive":{"post":{"description":"Restores a previously archived Thread to active Thread lists.","parameters":[{"description":"Thread ID returned by create thread. v1 IDs are bare ULIDs.","example":"01J00000000000000000000009","in":"path","name":"threadId","required":true,"schema":{"example":"01J00000000000000000000009","format":"ulid","pattern":"^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$","type":"string","x-default":"01J00000000000000000000009"}}],"security":[{"accessToken":[]}],"summary":"Unarchive a Thread","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"ok":{"const":true}},"required":["ok"],"type":"object"}}},"description":"Unarchived."},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}}},"security":[{"accessToken":[]}],"servers":[{"url":"https://cloud.mosoo.ai/api/v1"}]}