API Endpoints
Current Teamday API endpoint map for agent automation, streaming events, durable jobs, missions, and MCP clients.
API Endpoints
The canonical endpoint contract is the OpenAPI document:
GET https://app.teamday.ai/api/openapi.jsonUse this page as the human-readable map. All authenticated endpoints use:
Authorization: Bearer <teamday-service-token>Service tokens support least-privilege scopes such as agents:read, chats:write, jobs:read, jobs:write, missions:write, webhooks:write, and mcp. A token with * keeps full access.
Mutating JSON requests may include:
Idempotency-Key: <unique-key-for-this-operation>Base URLs
| Surface | Base URL |
|---|---|
| App/API | https://app.teamday.ai |
| OpenAPI | https://app.teamday.ai/api/openapi.json |
| Interactive reference | https://app.teamday.ai/api/reference |
| Agent-readiness manifest | https://app.teamday.ai/api/agent-readiness |
| SDK examples | https://app.teamday.ai/api/sdk-examples |
| MCP OAuth metadata | https://app.teamday.ai/.well-known/oauth-authorization-server |
Contract
| Method | Path | Purpose | Auth |
|---|---|---|---|
GET | /api/openapi.json | OpenAPI 3.1 contract | Public |
GET | /api/reference | Interactive API reference backed by the OpenAPI contract | Public |
GET | /api/sdk-examples | Generated-client commands and TypeScript/Python examples | Public |
GET | /api/agent-readiness | Machine-readable agent-readiness manifest | Public |
GET | /.well-known/teamday-agent-api | Well-known manifest for crawlers and agents | Public |
GET | /api/version | Deployed version metadata | Public |
Agents
| Method | Path | Purpose |
|---|---|---|
GET | /api/agents | List agents available to the organization |
POST | /api/agents | Create a Private Agent |
PATCH | /api/agents/{id} | Update an agent |
DELETE | /api/agents/{id} | Delete a Private Agent |
PATCH | /api/agents/{id}/install-state | Install, uninstall, or restore a library agent |
Chats
| Method | Path | Purpose |
|---|---|---|
GET | /api/chats | List chats |
POST | /api/chats | Create a durable chat |
GET | /api/chats/{id}/messages | Read chat messages and durable work summary |
POST | /api/chats/{id}/messages | Send a message to an agent |
GET | /api/chats/{id}/events | Stream chat events over Server-Sent Events |
PATCH | /api/chats/{id}/options | Update chat options |
DELETE | /api/chats/{id} | Delete a chat |
Jobs
Jobs are long-running work records. Use them when an agent starts work that may outlive a request.
| Method | Path | Purpose |
|---|---|---|
GET | /api/jobs | List jobs |
GET | /api/jobs/{id} | Read job status, metadata, artifacts, review state, and links |
GET | /api/jobs/{id}/events | Stream job events over Server-Sent Events |
GET | /api/jobs/{id}/lineage | Read related jobs |
GET | /api/jobs/{id}/transcript-events | Read transcript events |
POST | /api/jobs/{id}/approve | Approve reviewable work |
POST | /api/jobs/{id}/cancel | Cancel running work |
POST | /api/jobs/{id}/resume | Resume blocked work |
POST | /api/jobs/{id}/iterate | Request another iteration |
Missions
Missions define manual or scheduled recurring work for an agent.
| Method | Path | Purpose |
|---|---|---|
GET | /api/missions | List missions |
POST | /api/missions | Create a mission |
GET | /api/missions/{id} | Read a mission |
PATCH | /api/missions/{id} | Update a mission |
POST | /api/missions/{id}/tasks | Add a mission task |
PATCH | /api/missions/{id}/tasks/{taskId} | Update a mission task |
POST | /api/missions/{id}/tasks/{taskId}/start-work | Start long-running work from a task |
Workspaces And Files
| Method | Path | Purpose |
|---|---|---|
POST | /api/workspaces | Create a workspace |
POST | /api/workspaces/{id}/select | Set the active workspace |
POST | /api/workspaces/{id}/repos | Add a repository mount |
POST | /api/workspaces/{id}/repos/clone | Clone a repository mount |
POST | /api/workspaces/{id}/apps | Create a workspace app |
POST | /api/workspaces/{id}/files/preview | Create or fetch a file preview |
POST | /api/workspaces/{id}/files/share | Create a public file share |
POST | /api/workspaces/{id}/files/directory | Create a directory |
POST | /api/workspaces/{id}/files/move | Move a file or directory |
POST | /api/workspaces/{id}/data-blocks/query | Run a read-only data-block query |
MCP
Teamday exposes a Streamable HTTP MCP endpoint for MCP clients.
| Method | Path | Purpose | Auth |
|---|---|---|---|
POST | /mcp | Send MCP JSON-RPC or Streamable HTTP messages | OAuth mcp scope |
GET | /mcp | Open an MCP Streamable HTTP session | OAuth mcp scope |
DELETE | /mcp | Close an MCP session | OAuth mcp scope |
Event Streams
SSE endpoints return text/event-stream, send an initial connection comment, replay recent events, then stream live events and heartbeat comments.
| Stream | Events |
|---|---|
/api/chats/{id}/events | Chat message replay, assistant output, routing status, artifacts, review state |
/api/jobs/{id}/events | Job event replay, runner status, transcript output, artifact updates |
/mcp-app/jobs/{jobId}/events | Signed app stream for embedded MCP app surfaces |
Webhook Event Delivery
Teamday can push durable work state changes to an organization webhook. Configure the destination through the messaging integration API.
| Method | Path | Purpose |
|---|---|---|
GET | /api/messaging-integration | Read webhook/event delivery configuration |
PUT | /api/messaging-integration | Configure the HTTPS destination and enable delivery |
POST | /api/messaging-integration/signing-secret/rotate | Rotate the HMAC-SHA256 signing secret |
POST | /api/messaging-integration/test | Send a signed test delivery |
Webhook deliveries include:
Teamday-Event-Id: 01HX...
Teamday-Event-Type: job.done
Teamday-Delivery-Attempt: 1
Teamday-Timestamp: 1779330180
Teamday-Signature: t=1779330180,v1=<hex-hmac-sha256>
Idempotency-Key: 01HX...Verify Teamday-Signature by computing HMAC-SHA256(secret, "${timestamp}.${rawBody}") and comparing it to the v1 value. Treat Teamday-Event-Id as the idempotent event key. Teamday retries transient delivery failures with backoff delays of 0s, 1s, 2s, and 4s.
Rate-Limit Headers
Every API response includes transparent quota headers when rate limiting is active:
X-RateLimit-Limit: 900
X-RateLimit-Remaining: 899
X-RateLimit-Reset: 1779330180
RateLimit-Limit: 900
RateLimit-Remaining: 899
RateLimit-Reset: 60
RateLimit-Policy: 900;w=60When throttled, the API returns 429 and a Retry-After header.
The default production budget is 900 requests per minute per authenticated identity. Agents may use the full one-minute budget as a burst and should back off with Retry-After after a 429. High-volume enterprise workloads can be assigned a contract-specific limit without changing the header contract.
In production, rate-limit counters and idempotency replay state are stored in Redis so the behavior is consistent across API replicas.