◈ THALAMUS CUA
Documentation Get started How-to guides Key concepts The console Safety Evaluation Models Developers Your instance

Documentation › Developers

Developers: API, SDK & CLI

Reference· API, SDK, CLI, MCP

Everything you can do in the console you can do from code — create goals, start and supervise runs, read the evidence — so other systems and agents can hand ThalamusCUA work.

REST API

Everything the console does goes through the API at /v1, on the same address as the console: https://starcraft.staging.thalamuscua.thalamusaicloud.com/v1 for the sample instance used throughout these docs (https://<instance>.<environment>.thalamuscua.thalamusaicloud.com). Sign in with POST /v1/auth/login (a cookie) or OIDC. The API reference is at https://starcraft.staging.thalamuscua.thalamusaicloud.com/docs, and request and response schemas are in docs/contracts/. All paths below are under /v1.

Goals and runs

POST /goalsCreate a goal
POST /goals/{id}/plan · PUT /goals/{id}/planProduce, or edit, its plan
POST /executions · GET /executions · GET /executions/{id}Start, list and read runs
POST /executions/{id}/pause | resume | cancelControl a run
POST /executions/{id}/hints · /answersSend a hint, answer a question

Evidence

GET /executions/{id}/events · /traceThe trace events
GET /executions/{id}/report.md · /report.jsonReadable and structured reports
GET /agent-runs/{id}/steps · /recordingAn agent’s steps and screen recording
GET /artifacts/{id}/contentScreenshots and files

Supervision

GET /approvals · POST /approvals/{id}/decisionList and decide approvals
POST /agent-runs/{id}/takeover · /inputTake over the screen, and send mouse/keyboard input

Applications and environments

GET /applications · POST /applications/{id}/brief · /brief/draftApplications and their briefs
GET /environments · PATCH /environments/{id}Environments, address and login
POST /environments/{id}/snapshot · /resetSnapshot and reset

Evaluation, triggers and replay

POST /evaluations · GET /evaluations · GET /evaluations/failuresRun and read evaluations
POST /triggersExternal systems submit work
POST /executions/{id}/replays · GET /replays/{id}Replay a run
GET /skillsSkills each application supports

Models and documents

GET /models · PUT /modelsThe model for each role, and the lists they are chosen from (admins change them)
POST /models/catalog · DELETE /models/catalogAdd a model (it downloads on its server) or remove one you added
GET /documentsModel evaluations and benchmark scripts, as the Documents page lists them
GET /documents/file?path=…One listed document’s text; any path not listed is refused

Python SDK

Installed as cua-sdk: a small synchronous client over the API.

from cua.sdk import Client

client = Client(base_url="https://starcraft.staging.thalamuscua.thalamusaicloud.com")   # your instance, or CUA_API_URL
client.login(tenant="home", email="you@example.com", password="…")

goal = client.create_goal(
    text="Acknowledge the open alert for checkout latency",
    application_id="…",
    environment_id="…",
)
execution = client.start_execution(goal_id=goal["id"])
result = client.wait_execution(execution["id"])     # waits until it finishes

Also: get_execution, list_executions, list_approvals, decide_approval, list_skills, trigger, close. Errors raise ApiError.

Command line

cua-sdk submit      # create a goal and start it
cua-sdk wait        # wait until a run finishes
cua-sdk get         # read a run
cua-sdk approvals   # list approvals waiting
cua-sdk decide      # approve or reject one
cua-sdk skills      # list skills
cua-sdk trigger     # fire a trigger (service token, optional webhook)

Other ways in