REST API

Twin exposes a REST API that lets you create agents, trigger runs, manage schedules, and more — all programmatically.

Base URL

https://api.twin.so

Authentication

All requests require an API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Generate an API key from your Twin account or via the API itself (see below).

Error Handling

All error responses follow this format:

{
  "code": 3,
  "message": "Description of what went wrong",
  "details": []
}

API Keys

RESTful endpoints for managing API keys.

List API keys

GET /api/public/v1/access-api-keys

Returns all API keys for the authenticated user.Example

curl https://api.twin.so/api/public/v1/access-api-keys \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "keys": [
    {
      "keyId": "abc123",
      "name": "my-integration",
      "displayPrefix": "tw_live_abc...",
      "createdAt": 1706000000,
      "lastUsedAt": 1706100000
    }
  ]
}

Create an API key

POST /api/public/v1/access-api-keys

Creates a new API key. The full key is only returned once — store it securely.Request body

Field	Type	Required	Description
`name`	string	No	Optional name for the key

Example

curl -X POST https://api.twin.so/api/public/v1/access-api-keys \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-integration"}'

Response

{
  "keyId": "abc123",
  "name": "my-integration",
  "apiKey": "tw_live_...",
  "displayPrefix": "tw_live_abc..."
}

The apiKey field is only returned at creation time. Store it immediately.

Revoke an API key

DELETE /api/public/v1/access-api-keys/{keyId}

Permanently revokes an API key. Any requests using it will stop working immediately.Path parameters

Field	Type	Required	Description
`keyId`	string	Yes	The ID of the key to revoke

Example

curl -X DELETE https://api.twin.so/api/public/v1/access-api-keys/abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Agents

Create, list, update, and delete agents. All agent endpoints use POST with a JSON body.

Create an agent

POST /twin.service.TwinService/CreateAgentOnly

Creates a new agent with a goal description.Request body

Field	Type	Required	Description
`goal`	string	Yes	Natural-language description of the task
`projectId`	string	No	Project to assign the agent to

Example

curl -X POST https://api.twin.so/twin.service.TwinService/CreateAgentOnly \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"goal": "Monitor competitor pricing on stripe.com weekly"}'

Response

{
  "agentId": "agent_abc123"
}

Get an agent

POST /twin.service.TwinService/GetAgent

Returns full details for a specific agent.Request body

Field	Type	Required	Description
`agentId`	string	Yes	The agent’s ID

Example

curl -X POST https://api.twin.so/twin.service.TwinService/GetAgent \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agentId": "agent_abc123"}'

Response

{
  "agent": {
    "agentId": "agent_abc123",
    "goal": "Monitor competitor pricing on stripe.com weekly",
    "latestRunId": "run_xyz789",
    "lastActivityAt": "2026-02-20T14:30:00Z",
    "latestRunIsFinished": true,
    "hasRuns": true,
    "projectId": "proj_001",
    "deploymentState": "deployed",
    "deployedAt": "2026-02-18T10:00:00Z"
  }
}

List agents

POST /twin.service.TwinService/ListAgents

Returns all agents, optionally filtered by project.Request body

Field	Type	Required	Description
`projectId`	string	No	Filter by project (omit for all)

Example

curl -X POST https://api.twin.so/twin.service.TwinService/ListAgents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response

{
  "agents": [
    {
      "agentId": "agent_abc123",
      "goal": "Monitor competitor pricing on stripe.com weekly",
      "latestRunIsFinished": true,
      "hasRuns": true,
      "deploymentState": "deployed"
    }
  ]
}

Update agent goal

POST /twin.service.TwinService/UpdateAgentGoal

Updates the natural-language goal for an existing agent.Request body

Field	Type	Required	Description
`agentId`	string	Yes	The agent’s ID
`newGoal`	string	Yes	The updated goal

Example

curl -X POST https://api.twin.so/twin.service.TwinService/UpdateAgentGoal \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent_abc123",
    "newGoal": "Monitor competitor pricing on stripe.com and notion.so daily"
  }'

Response

{
  "success": true,
  "previousGoal": "Monitor competitor pricing on stripe.com weekly"
}

Delete an agent

POST /twin.service.TwinService/DeleteAgent

Permanently deletes an agent and all associated data.Request body

Field	Type	Required	Description
`agentId`	string	Yes	The agent’s ID

Example

curl -X POST https://api.twin.so/twin.service.TwinService/DeleteAgent \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agentId": "agent_abc123"}'

Response

{
  "deleted": true
}

Runs

Trigger agent executions, check status, and retrieve results.

Start a run

POST /twin.service.TwinService/StartRun

Triggers a new run for a deployed agent.Request body

Field	Type	Required	Description
`agentId`	string	Yes	The agent to run

Example

curl -X POST https://api.twin.so/twin.service.TwinService/StartRun \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agentId": "agent_abc123"}'

Response

{
  "agentId": "agent_abc123",
  "runId": "run_xyz789"
}

List runs

POST /twin.service.TwinService/ListAgentRuns

Returns paginated run history for an agent with optional filters.Request body

Field	Type	Required	Description
`agentId`	string	Yes	The agent’s ID
`page`	integer	No	Page number (default 1)
`pageSize`	integer	No	Results per page (default 20)
`filterStatus`	string	No	`"finished"`, `"running"`, or omit for all
`filterStartedAfter`	string	No	ISO 8601 date — only runs after this time
`filterStartedBefore`	string	No	ISO 8601 date — only runs before this time

Example

curl -X POST https://api.twin.so/twin.service.TwinService/ListAgentRuns \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent_abc123",
    "page": 1,
    "pageSize": 10,
    "filterStatus": "finished"
  }'

Response

{
  "runs": [
    {
      "runId": "run_xyz789",
      "agentId": "agent_abc123",
      "status": "finished",
      "startedAt": "2026-02-20T14:30:00Z",
      "finishedAt": "2026-02-20T14:32:15Z"
    }
  ],
  "totalRuns": 42,
  "page": 1,
  "pageSize": 10
}

Get run detail

POST /twin.service.TwinService/GetRunDetail

Returns detailed information for a specific run, including step-by-step execution data.Request body

Field	Type	Required	Description
`runId`	string	Yes	The run’s ID

Example

curl -X POST https://api.twin.so/twin.service.TwinService/GetRunDetail \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"runId": "run_xyz789"}'

Quick Reference

Action	Method	Endpoint
List API keys	`GET`	`/api/public/v1/access-api-keys`
Create API key	`POST`	`/api/public/v1/access-api-keys`
Revoke API key	`DELETE`	`/api/public/v1/access-api-keys/{keyId}`
Create agent	`POST`	`/twin.service.TwinService/CreateAgentOnly`
Get agent	`POST`	`/twin.service.TwinService/GetAgent`
List agents	`POST`	`/twin.service.TwinService/ListAgents`
Update agent goal	`POST`	`/twin.service.TwinService/UpdateAgentGoal`
Delete agent	`POST`	`/twin.service.TwinService/DeleteAgent`
Start run	`POST`	`/twin.service.TwinService/StartRun`
List runs	`POST`	`/twin.service.TwinService/ListAgentRuns`
Get run detail	`POST`	`/twin.service.TwinService/GetRunDetail`

API key endpoints (/api/public/v1/...) use standard REST methods (GET, POST, DELETE). All other endpoints use POST with a JSON body — this is the gRPC-gateway convention used by Twin’s API.

Get Started

Key Concepts

Guide

Base URL

Authentication

Error Handling

API Keys

List API keys

Create an API key

Revoke an API key

Agents

Create an agent

Get an agent

List agents

Update agent goal

Delete an agent

Runs

Start a run

List runs

Get run detail

Quick Reference

Get your API key

Get Started

Key Concepts

Guide

​Base URL

​Authentication

​Error Handling

​API Keys

​List API keys

​Create an API key

​Revoke an API key

​Agents

​Create an agent

​Get an agent

​List agents

​Update agent goal

​Delete an agent

​Runs

​Start a run

​List runs

​Get run detail

​Quick Reference

Get your API key

Base URL

Authentication

Error Handling

API Keys

List API keys

Create an API key

Revoke an API key

Agents

Create an agent

Get an agent

List agents

Update agent goal

Delete an agent

Runs

Start a run

List runs

Get run detail

Quick Reference