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

Contract

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:

Agents

Chats

Jobs

Jobs are long-running work records. Use them when an agent starts work that may outlive a request.

Missions

Missions define manual or scheduled recurring work for an agent.

Files And Folders

Files live in one organization-wide tree and are addressed by absolute path (/product, /marketing/blog/launch.md). Directories are ordinary directories; there is no container to create or select before using them.

Projects, Repositories, And Apps

Projects, apps, chats, and missions each carry an explicit working directory (cwd), an absolute organization path chosen at creation. It does not change when a user later browses another directory.

Legacy workspace routes

Earlier Teamday versions grouped files under /api/workspaces/{id}/... and accepted a workspace_id field on chats, missions, and projects. Those routes and fields still resolve for explicit IDs that already exist, so old links and stored integrations keep working, and they still emit the workspace.*, workspace_repository.*, and workspace_file.changed webhook event types. The old workspaces:read / workspaces:write token scopes are accepted as aliases of files:read / files:write. Do not build new integrations on them: use the path-based /api/files routes and cwd fields above.

MCP

Teamday exposes a Streamable HTTP MCP endpoint for MCP clients.

Event Streams

SSE endpoints return text/event-stream, send an initial connection comment, replay recent events, then stream live events and heartbeat comments.

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.

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.*, resource.*, service_token.*, and webhook.*. Legacy file and repository event types are listed under Legacy workspace routes.

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.