# Team Time API for AI tools

Use the Team Time HTTP API at https://time.wscm.eu/api/v1.
Read https://time.wscm.eu/api/v1/ai.md and https://time.wscm.eu/api/v1/openapi.json first.
The API key is configured in TEAM_TIME_API_KEY. Send Authorization: Bearer $TEAM_TIME_API_KEY. Keep it out of URLs, logs, and saved prompts.
Keys can target an entire organization or one project. Start with GET /context to confirm access and available operations, then /projects, /members, and /workflow. Task assigneeId is a member's userId; membership id is used for team administration. Resolve names to IDs; ask if ambiguous.
Use a fresh UUID Idempotency-Key for every mutation, and repeat the exact key and payload if its response is lost. Read versions before writing. Preserve omitted task fields; use null to unassign or clear a due date. On 409 stale_version re-read and reconsider before a new command.
You need HTTP/tool execution or an integration that imports OpenAPI to call this API.

## Core workflow

1. GET /context to confirm the organization, acting user, access.type (organization or project), access.projectId/access.projectName, and allowed operations.
2. GET /projects, /members, /workflow, and /tags to resolve IDs. Follow page.nextCursor until null, passing cursor and the same limit/filters. Member userId is a task's assigneeId; member id is the membership ID used in /members/{id}.
3. POST /tasks with projectId and title. Optional assigneeId/dueOn default to null; description defaults to "" and tags to []. Tags are names, not IDs. New tasks must use an unfinished status. A response includes data.id, data.version, and data.statusId.
4. PATCH /tasks/{id} with expectedVersion and only the fields to change: title, description, result, projectId, assigneeId, dueOn, tags. null clears assignee/due date; [] clears tags. Other fields stay unchanged.
5. POST /tasks/{id}/status with expectedVersion, statusId, and expectedWorkflowVersion from GET /workflow. Moving an unassigned task into an In progress status takes it for the acting user and shows this key's name as the agent (assigneeAgentName); send claimIfUnassigned: false to leave it unassigned. Alternatively use /complete (optional result) or /reopen with expectedVersion. Use /position with beforeId and both versions for board order.

## Request example

Store the key in TEAM_TIME_API_KEY and the deployment origin in TEAM_TIME_ORIGIN. Use secret configuration, not a shared prompt. This curl is an example; resolve the placeholders before calling:

```bash
curl "$TEAM_TIME_ORIGIN/api/v1/tasks" \
  -H "Authorization: Bearer $TEAM_TIME_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" \
  --data '{"projectId":"<project-id>","title":"Prepare launch checklist","description":"Include rollout and verification","assigneeId":null,"dueOn":null,"tags":["Launch"]}'
```

Generate and retain the command UUID before the first request if a retry may be needed. Do not generate a fresh UUID for a retry. Empty actions still send {} with Content-Type: application/json. DELETE sends expectedVersion in the query and Idempotency-Key in a header.

## Organization and project access

Choose Entire organization or Specific project when creating a key in Settings → API keys. Permissions are a separate upper bound. A project key can discover only its selected project, that project's tasks and tags, and its linked client. Search, creator-owned time, reports, CSV and client summaries are automatically limited to that project, even when projectId is omitted from filters. Task/time creation still requires the exact permitted projectId. Explicit out-of-target resources, filters and move destinations return 404 resource_not_found.

Organization member IDs/names and shared workflow remain readable with the corresponding scopes so tasks can be assigned and statuses changed. A project key cannot change organization settings, clients, team membership/invitations or workflow; create projects; or read/submit/approve whole-week reviews. Those operations require an organization-wide key and return 403. Check /context.operations before calling.

Project keys can update/archive/restore/delete only their selected project when permitted. They cannot link it to a different client or move tasks/time outside it. Timer responses omit other projects' task totals, task identity and private notes; timer mutations return 409 timer_outside_project if the creator's current or paused timer is outside the target. Manage that timer in the app first.

Access targets cannot be edited: replace and revoke the key to change them. Existing keys keep organization access. Project deletion permanently revokes its keys; archive preserves historical reads and existing domain rules. Authorization is checked before idempotent replay, including whether a task has since moved outside the target. Project credentials use the ttp_ prefix, which older server versions reject; organization credentials retain tt_. Keep these credentials in secret configuration regardless of prefix.

## Limits and conflict handling

- 120 requests/minute/key and 600/minute/organization; invitation sending is limited to 10/minute/organization. Respect Retry-After on 429. JSON request bodies are capped at 64 KiB.
- Collection limit defaults to 50 and must be 1–100. Cursors belong to one organization, resource, filter set, and limit. Traversal is live rather than a frozen snapshot.
- Retry uncertain network failures with exactly the original method/path/body and Idempotency-Key for up to seven days. The original response is replayed. Reusing that key for a different payload returns 409 idempotency_conflict. Invalid/revoked credentials cannot replay receipts.
- 409 stale_version: re-read and reconsider whether the requested action still makes sense, then use the new versions and a new key. Do not overwrite newer work automatically.
- Completing a task (including a completed status change) atomically stops only the key creator’s matching timer and preserves recorded time. Another member’s running timer blocks completion; unrelated timers remain unchanged. Re-read GET /timer after completion for its new version.
- task_has_time, task_locked, timer_running, and time_overlap conflicts preserve application rules. Do not bypass them by deleting history or changing another person's timer.
- Scopes are the upper bound; current creator role and resource rules apply too. Removing/demoting the creator or archiving the organization permanently revokes its keys.
- Dates use YYYY-MM-DD; timestamps are ISO 8601 instants. Week paths use a Monday. Time corrections, timer commands and week reviews use the shared per-user time version (GET /timer, /time-entries meta.version, or /weeks/{week}).
- Time/timer endpoints operate on the key creator only. Reports omit all private work-note content, including from CSV. Team review detail also excludes those notes. No API accepts an acting-user override.
- Report exports and client summaries require sampledAt/fingerprint from GET /reports with the exact same filters. Snapshots expire after 24 hours. Reports are bounded by existing service limits (up to 366 days and 10,000 entries/tasks); narrow filters if requested.
- /members/{membership-id}/reassign-tasks takes assigneeId plus tasks:[{id,expectedVersion}], at most 100 distinct tasks currently assigned to that membership. The batch is atomic.
- Credential management, organization lifecycle, joining/switching accounts, and ownership changes require a signed-in human session. Task-agent coordination is available through dedicated chat-run, presence, task-link and message endpoints after a human enables the project in task details. It does not share native chat transcripts or release task claims on timeout. The separate team-time-mcp package supplies Codex hooks and task tools. Bulk import, generic webhooks, attachments and general-purpose comments are not implemented.

## Operations

- POST /coordination/runs — Register a chat run. Permissions: tasks:read, tasks:write. Access: organization or selected project.
- POST /coordination/heartbeat — Refresh installation connectivity and chat lifecycle. Permissions: tasks:read, tasks:write. Access: organization or selected project.
- GET /tasks/{id}/agents — Read task chats, presence and conversation. Permissions: tasks:read. Access: organization or selected project.
- POST /tasks/{id}/agents — Link this chat and declare work scope. Permissions: tasks:read, tasks:write. Access: organization or selected project.
- POST /tasks/{id}/agent-messages — Ask an active agent or leave a task message. Permissions: tasks:read, tasks:write. Access: organization or selected project.
- GET /agent-messages/{id} — Read reply or timeout status. Permissions: tasks:read. Access: organization or selected project.
- POST /agent-messages/{id}/reply — Reply as the addressed chat run. Permissions: tasks:read, tasks:write. Access: organization or selected project.
- GET /coordination/inbox — Read this installation’s undelivered task messages. Permissions: tasks:read. Access: organization or selected project.
- POST /coordination/ack — Acknowledge delivered context without implying a reply. Permissions: tasks:read, tasks:write. Access: organization or selected project.
- GET /invitations/{id} — Read an organization invitation. Permissions: members:read, team:write. Access: organization only.
- GET /context — Discover the organization, identity, scopes, and available operations. Permissions: any valid key. Access: organization or selected project.
- GET /organization — Read organization settings. Permissions: organization:read. Access: organization or selected project.
- PATCH /organization — Update organization name or timezone. Permissions: organization:read, organization:write. Access: organization only.
- GET /tasks — Search and paginate all tasks, including completed history. Permissions: tasks:read. Access: organization or selected project.
- POST /tasks — Create and optionally assign a task. Permissions: tasks:read, tasks:write. Access: organization or selected project.
- GET /tasks/{id} — Read a task and its version. Permissions: tasks:read. Access: organization or selected project.
- PATCH /tasks/{id} — Atomically update supplied task metadata. Permissions: tasks:read, tasks:write. Access: organization or selected project.
- DELETE /tasks/{id} — Delete a task without recorded time. Permissions: tasks:read, tasks:delete. Access: organization or selected project.
- POST /tasks/{id}/status — Move a task to a discovered workflow status. Permissions: tasks:read, tasks:write, workflow:read. Access: organization or selected project.
- POST /tasks/{id}/complete — Complete a task and optionally save its result. Permissions: tasks:read, tasks:write. Access: organization or selected project.
- POST /tasks/{id}/reopen — Reopen a completed task. Permissions: tasks:read, tasks:write. Access: organization or selected project.
- POST /tasks/{id}/position — Reorder a task within its current board column. Permissions: tasks:read, tasks:write, workflow:read. Access: organization or selected project.
- GET /projects — Discover active and archived projects. Permissions: projects:read. Access: organization or selected project.
- GET /projects/{id} — Read a project. Permissions: projects:read. Access: organization or selected project.
- POST /projects — Create a project with an optional existing client. Permissions: projects:read, projects:write. Access: organization only.
- PATCH /projects/{id} — Update supplied project fields. Permissions: projects:read, projects:write. Access: organization or selected project.
- DELETE /projects/{id} — Delete a project without recorded time. Permissions: projects:read, projects:delete. Access: organization or selected project.
- POST /projects/{id}/archive — Archive a project. Permissions: projects:read, projects:write. Access: organization or selected project.
- POST /projects/{id}/restore — Restore a project. Permissions: projects:read, projects:write. Access: organization or selected project.
- GET /clients — Discover clients. Permissions: clients:read. Access: organization or selected project.
- GET /clients/{id} — Read a client. Permissions: clients:read. Access: organization or selected project.
- POST /clients — Create a client. Permissions: clients:read, clients:write. Access: organization only.
- PATCH /clients/{id} — Rename a client. Permissions: clients:read, clients:write. Access: organization only.
- POST /clients/{id}/archive — Archive a client. Permissions: clients:read, clients:write. Access: organization only.
- POST /clients/{id}/restore — Restore a client. Permissions: clients:read, clients:write. Access: organization only.
- GET /members — Discover membership IDs and user IDs for assignment. Permissions: members:read. Access: organization or selected project.
- GET /workflow — Read statuses, columns, and workflow version. Permissions: workflow:read. Access: organization or selected project.
- PUT /workflow — Atomically save workflow configuration and replacement mappings. Permissions: workflow:read, workflow:write. Access: organization only.
- GET /tags — Discover shared workspace tags. Permissions: tasks:read. Access: organization or selected project.
- GET /time-entries — Read creator-owned entries for an organization-local day. Permissions: time:own:read. Access: organization or selected project.
- GET /time-entries/{id} — Read a creator-owned time entry. Permissions: time:own:read. Access: organization or selected project.
- POST /time-entries — Create creator-owned manual time. Permissions: time:own:read, time:own:write. Access: organization or selected project.
- PATCH /time-entries/{id} — Correct creator-owned time. Permissions: time:own:read, time:own:write. Access: organization or selected project.
- DELETE /time-entries/{id} — Delete creator-owned manual time. Permissions: time:own:read, time:own:write. Access: organization or selected project.
- GET /timer — Read the creator's current timer. Permissions: timers:own:read. Access: organization or selected project.
- POST /timer/start — Start or switch the creator's timer. Permissions: timers:own:read, timers:own:write. Access: organization or selected project.
- POST /timer/pause — pause the creator's timer. Permissions: timers:own:read, timers:own:write. Access: organization or selected project.
- POST /timer/resume — resume the creator's timer. Permissions: timers:own:read, timers:own:write. Access: organization or selected project.
- POST /timer/stop — stop the creator's timer. Permissions: timers:own:read, timers:own:write. Access: organization or selected project.
- PATCH /timer/note — Save the creator's private active work note. Permissions: timers:own:read, timers:own:write. Access: organization or selected project.
- GET /weeks/{week} — Read the creator's week and version. Permissions: reviews:own:read. Access: organization only.
- POST /weeks/{week}/submit — submit the creator's whole week. Permissions: reviews:own:read, reviews:own:write. Access: organization only.
- POST /weeks/{week}/withdraw — withdraw the creator's whole week. Permissions: reviews:own:read, reviews:own:write. Access: organization only.
- GET /reviews — Read the submitted review queue for a week. Permissions: reviews:team:read. Access: organization only.
- GET /reviews/{userId}/{week} — Read a team member's review without private work notes. Permissions: reviews:team:read. Access: organization only.
- POST /reviews/{userId}/{week}/approve — approve a team member's week. Permissions: reviews:team:read, reviews:team:write. Access: organization only.
- POST /reviews/{userId}/{week}/return — return a team member's week. Permissions: reviews:team:read, reviews:team:write. Access: organization only.
- POST /reviews/{userId}/{week}/reopen — reopen a team member's week. Permissions: reviews:team:read, reviews:team:write. Access: organization only.
- GET /reports — Read a report without private work notes. Permissions: reports:read. Access: organization or selected project.
- GET /reports/entries.csv — Export a matching entries report snapshot. Permissions: reports:read. Access: organization or selected project.
- GET /reports/tasks.csv — Export a matching tasks report snapshot. Permissions: reports:read. Access: organization or selected project.
- POST /reports/client-summary — Generate a client summary without sending it. Permissions: reports:read. Access: organization or selected project.
- GET /invitations — Read organization invitations. Permissions: members:read, team:write. Access: organization only.
- POST /invitations — Invite an admin or member. Permissions: members:read, team:write. Access: organization only.
- POST /invitations/{id}/cancel — Cancel a pending invitation. Permissions: members:read, team:write. Access: organization only.
- POST /invitations/{id}/send — Send an invitation through the configured email provider. Permissions: members:read, team:write. Access: organization only.
- PATCH /members/{id} — Change a non-owner member's role. Permissions: members:read, team:write. Access: organization only.
- DELETE /members/{id} — Remove a non-owner member. Permissions: members:read, team:write. Access: organization only.
- POST /members/{id}/reassign-tasks — Atomically reassign selected tasks from a member. Permissions: members:read, team:write, tasks:read, tasks:write. Access: organization only.

Read https://time.wscm.eu/api/v1/openapi.json for the exact schemas, response shapes, required properties, and stable operation IDs. Human reference: https://time.wscm.eu/api/docs.