API quickstart

This guide requires a deployment that serves the Project-level /api/v2 creation and file routes. Configure your own model-provider credentials in the Project; platform-funded model access is not included.

A Thread is the public API name for a durable Session. A Run executes one turn using its admitted runtime and workspace. The v1 published-Agent API keeps its name and behavior; the v1 quickstart still applies.

Configure your own model-provider credentials in a Project and create its API key. A direct request selects the harness, provider, model and instructions; it creates no Agent. An owned saved Agent is an optional preset. A Project key cannot access another Project. Keep it on your backend; your app still authenticates its own users.

Create and continue

Set MOSOO_API_BASE to the verified deployment's /api/v2 URL and provide MOSOO_PROJECT_ID and MOSOO_API_TOKEN through backend secret storage. Creation without input returns an idle Thread and queues no model work. Copy the returned thread.id into MOSOO_THREAD_ID; all later turns use this same ID.

Choose a supported harness/provider/model combination for the configured Project. The example uses openai-runtime; Claude Code uses claude-agent-sdk with an available Anthropic model and credentials. Selection is fixed for this Session. Unsupported combinations or unavailable credentials return readiness_blocked without a fallback. Inline creation returns agent_id: null.

On a target that includes Pi, use harness: "pi" with a compatible Project provider and model. Custom providers use provider: "openai-compatible" and the exact configured model ID; their credential selects the upstream protocol. See Pi runtime for the protocol matrix and a complete API/CLI example.

To reuse a saved Agent, replace the entire configuration with {type: "agent", agent_id: "your Agent ID"}. Do not combine preset and inline fields. Existing /agents/{agentId}/threads remains a preset adapter.

Optional file inputs can be uploaded without an Agent:

curl -X POST "$MOSOO_API_BASE/projects/$MOSOO_PROJECT_ID/files" \
  -H "Authorization: Bearer $MOSOO_API_TOKEN" \
  -F "file=@./input.csv"

Save the returned file.id; include it in the create body as resources: [{type: "file", file_id: "the returned ID"}]. The file and any preset must belong to the selected Project. CLI login may select an owned Project explicitly; a Project key remains bound to its own Project.

curl -X POST "$MOSOO_API_BASE/projects/$MOSOO_PROJECT_ID/threads" \
  -H "Authorization: Bearer $MOSOO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: durable-create-1" \
  -d '{"configuration":{"type":"inline","harness":"openai-runtime","provider":"openai","model":"gpt-5.6-luna","instructions":"Use tools to analyze files and preserve working state for follow-up."}}'

curl -X POST "$MOSOO_API_BASE/threads/$MOSOO_THREAD_ID/events" \
  -H "Authorization: Bearer $MOSOO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: durable-turn-1" \
  -d '{"events":[{"type":"user_message","text":"Read the inputs and write outputs/report.md."}]}'

curl "$MOSOO_API_BASE/threads/$MOSOO_THREAD_ID" \
  -H "Authorization: Bearer $MOSOO_API_TOKEN"
curl "$MOSOO_API_BASE/threads/$MOSOO_THREAD_ID/files" \
  -H "Authorization: Bearer $MOSOO_API_TOKEN"
curl "$MOSOO_API_BASE/threads/$MOSOO_THREAD_ID/usage?limit=100" \
  -H "Authorization: Bearer $MOSOO_API_TOKEN"

Recovery, files and usage

Uploads are optional. For uploaded inputs use the existing multipart file flow; for public repositories an exact URL and commit SHA can be supplied as input. The Agent may fetch that content with tools when its environment permits it. Persist the commit used so the analysis is reproducible.

Every new Session has its own execution workspace. Agent presets do not share a machine or workspace across Sessions. Existing shared Sessions require a separately verified migration; creating a Session does not perform that migration.

A successful Run commits workspace files and the native runtime continuation. After container reclamation, the same Session restores that committed state. Recovery failure is explicit; a new empty workspace is not a substitute for continuing previous work. Files outside outputs/ can be workspace state without being public artifacts. Failed or cancelled work is not a new successful checkpoint.

Formal and API-used Sessions have no inactivity deadline. After an idle interval, send the next input to the same Session ID; its admitted configuration and committed workspace/native context remain the continuation source. Old recorded recovery deadlines are ignored.

Only Cloud debug Previews with an explicit cleanup policy may be removed after 30 days without message, Run or file activity. Console login and history reads do not renew that period. This does not expire formal API Sessions. A separately reviewed legacy Session may be read-only while retaining history and saved files. Permanent deletion remains explicit.

Clock-controlled and forced-cold tests do not establish real elapsed-day survival. Check the target deployment’s acceptance evidence before relying on a migrated legacy Session.

Usage is paginated in ID order. Pass nextCursor as after and stop at null. Null token or cost fields mean unreported, never zero. reportedCostUsd is a runtime estimate, not settled billing. Inspect usageContract before combining cache/token buckets; in-progress observations can change when polled again.

Use a stable Idempotency-Key when retrying the identical request; use a new key for a new turn. Changed content, instructions, model or configuration source with the same key is a conflict. Project keys and CLI login selecting that Project share this receipt boundary. An interrupted committed creation recovers the original Session even if its preset has been edited or removed. A second concurrent turn is rejected; wait for the current Run or interrupt it.

The v2 CLI module is public-thread-api-v2; v1 remains public-thread-api. Both support file upload, wait and transcript helpers. After upgrading, sign in for the selected target to configure v2; logged-out credentials are not silently restored. Read the v2 API reference.

Save the same creation JSON shown above as session.json. The updated v2 CLI selects the Project explicitly; the JSON still chooses inline configuration or an Agent preset. Add returned file IDs to its resources when attaching uploaded inputs.

mosoo public-thread-api-v2 files upload --project-id "$MOSOO_PROJECT_ID" --file ./input.csv -o json
mosoo public-thread-api-v2 threads create --project-id "$MOSOO_PROJECT_ID" --file ./session.json -o json

This release uses your own model-provider account configured in the Project (BYOK). The provider charges that account. Per-turn monetary limits are outside this release; usage and estimated costs remain available. Platform-supplied models, recharge and commercial usage billing are separate future work and do not block this Session API release. Existing customer migration is a separately reviewed operation, not a side effect of these endpoints.