Skip to content
txcasttxcasttxcast docs

Use the Agent REST API v2

The base URL is:

https://api.txcast.com/agent/v2

The authoritative reference is the live OpenAPI 3.1 document. The v2 contract is intentionally breaking; do not send legacy graph definitions or v1 run commands to it.

REST accepts a newly issued manual txc_ credential. OAuth tokens are resource-bound to MCP v2 and should be used through that transport.

Read context

Section titled “Read context”
Terminal window
curl --fail-with-body \
  -H "Authorization: Bearer $TXCAST_AGENT_TOKEN" \
  https://api.txcast.com/agent/v2/context

Every scoped route names an organisation. For example:

GET /agent/v2/organisations/{organisationId}/audit-events
GET /agent/v2/organisations/{organisationId}/controlled-accounts
POST /agent/v2/organisations/{organisationId}/controlled-accounts
GET /agent/v2/organisations/{organisationId}/registry
POST /agent/v2/organisations/{organisationId}/registry/accounts
GET /agent/v2/organisations/{organisationId}/contracts
POST /agent/v2/organisations/{organisationId}/contracts/inspect
POST /agent/v2/organisations/{organisationId}/contracts
GET /agent/v2/organisations/{organisationId}/workflows
GET /agent/v2/organisations/{organisationId}/workflows/{workflowId}/revisions
GET /agent/v2/organisations/{organisationId}/runs
POST /agent/v2/organisations/{organisationId}/workflow-source/validate
POST /agent/v2/organisations/{organisationId}/workflows
PUT /agent/v2/organisations/{organisationId}/workflows/{workflowId}/source
POST /agent/v2/organisations/{organisationId}/workflows/{workflowId}/restores
POST /agent/v2/organisations/{organisationId}/workflows/{workflowId}/fork

Use the OpenAPI document for exact workflow CAS, run-version, pagination, and body schemas. It also defines every address-book, controlled-account, and contract read/update/delete route, including expectedUpdatedAt and ABI-digest concurrency fields.

Save and restore bodies use the current workflow CAS:

{
    "protocol": "txcast-workflow-linear-cas-v1",
    "workflowId": "workflow UUID",
    "version": 4,
    "currentRevisionId": "revision UUID"
}

After a 409, keep the proposed source in the client. Read the current workflow, resolve the conflict, and retry with a new CAS.

Mutations

Section titled “Mutations”

Every mutation requires:

Authorization: Bearer txc_…
Txcast-Agent-Name: your-client-name
Txcast-Agent-Version: your-client-version
Idempotency-Key: a-stable-key-for-this-exact-operation
Content-Type: application/json

The organisation ID, source/body identity, and caller provenance are bound into idempotency. Reusing a key with changed input conflicts.

Isolation

Section titled “Isolation”

Agent routes accept bearer credentials and reject browser session cookies. Browser action routes accept sessions and do not accept an agent bearer. This is why REST v2 cannot answer human effects or submit signatures even when the calling user could do so in the browser.