API Endpoints

The canonical endpoint contract is the OpenAPI document:

GET https://app.teamday.ai/api/openapi.json

Use 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
Deprecation policy	https://app.teamday.ai/api/deprecation-policy
Rate-limit policy	https://app.teamday.ai/api/rate-limits
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	/api/deprecation-policy	Versioning, compatibility, deprecation, and sunset policy	Public
GET	/api/rate-limits	Rate-limit tiers, identity model, headers, and retry policy	Public
GET	/.well-known/teamday-agent-api	Well-known manifest for crawlers and agents	Public
GET	/api/version	Deployed version metadata	Public

Versioning And Deprecation

Teamday uses date-based API contract versions. Breaking changes require a new version and migration guide. Documented endpoints remain backward compatible for at least 12 months after a replacement is published.

Deprecation policy:

Signal	Contract
Deprecation notice	At least 180 days
Sunset notice	At least 365 days
Deprecation header	Returned when a documented endpoint has an active deprecation date
Sunset header	Returned with the removal date after the migration window begins
Link header	Includes rel="deprecation", rel="sunset", or rel="successor-version" when applicable

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 and optional event_types subscriptions through the messaging integration API. Job lifecycle events are specialized, and every successful mutating JSON API request also emits a typed API mutation event when delivery is enabled and the event matches the subscription.

Method	Path	Purpose
GET	/api/messaging-integration	Read webhook/event delivery configuration
GET	/api/messaging-integration/deliveries	List durable webhook delivery attempts
POST	/api/messaging-integration/deliveries/{id}/redeliver	Redeliver a retained webhook event and append the new attempt to the ledger
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: agent.updated
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.

Use event_types to subscribe to exact events such as agent.updated or wildcard families such as job.*. An empty list means all events.

Each send attempt is written to the durable delivery ledger. GET /api/messaging-integration/deliveries returns one row per attempt with event ID, event type, source, attempt number, status, HTTP status, error, duration, and a redacted destination host. Use limit and cursor; responses include next_cursor when more ledger rows are available. POST /api/messaging-integration/deliveries/{id}/redeliver lets an owner replay a retained event to the current configured destination; the replay is signed with the current secret and creates new ledger rows for the redelivery attempts.

Core event families include agent.*, chat.*, job.*, mission.*, mission_task.*, workspace.*, workspace_repository.*, workspace_file.changed, resource.*, service_token.*, and webhook.*.

Rate-Limit Headers

Every API response includes transparent quota headers when rate limiting is active:

X-RateLimit-Limit: 3000
X-RateLimit-Remaining: 2999
X-RateLimit-Reset: 1779330180
X-RateLimit-Burst: 3000
X-RateLimit-Window: 60
X-RateLimit-Scope: authenticated-identity
RateLimit-Limit: 3000
RateLimit-Remaining: 2999
RateLimit-Reset: 60
RateLimit-Policy: 3000;w=60

When throttled, the API returns 429 and a Retry-After header.

The default production budget is 3000 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.

The machine-readable policy is available at https://app.teamday.ai/api/rate-limits. It describes the identity order (bearer_service_token, session_cookie, then remote_ip), the fixed 60-second window, enterprise tier behavior, and concrete normal/throttled response examples.

In production, rate-limit counters and idempotency replay state are stored in Redis so the behavior is consistent across API replicas.