{"openapi":"3.1.0","info":{"title":"Taskhold API","version":"1.1.0","description":"REST API behind Taskhold, a task list shared by a person and their coding agents. The same API key works for the MCP server at https://taskhold.com/api/mcp, which is the easier way to connect an agent. Changes made with an API key are recorded as made by an agent. Changelog: https://taskhold.com/changelog","contact":{"email":"hello@greatwork.company"},"termsOfService":"https://taskhold.com/terms"},"servers":[{"url":"https://taskhold.com"}],"security":[{"bearer":[]}],"externalDocs":{"description":"Setup per agent","url":"https://taskhold.com/for"},"paths":{"/api/tasks":{"get":{"summary":"List tasks","description":"Tasks for the key's account, newest first, with optional filters.","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["todo","in_progress","blocked","done"]},"description":"Only tasks in this status"},{"name":"priority","in":"query","schema":{"type":"string","enum":["low","medium","high","urgent"]},"description":"Only tasks with this priority"},{"name":"project_id","in":"query","schema":{"type":"string","format":"uuid"},"description":"Only tasks in this project"},{"name":"created_by","in":"query","schema":{"type":"string","enum":["human","agent"]},"description":"Only tasks created by a person or by an agent"},{"name":"limit","in":"query","schema":{"type":"integer","default":50},"description":"Page size"},{"name":"offset","in":"query","schema":{"type":"integer","default":0},"description":"Rows to skip"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"tasks":{"type":"array","items":{"$ref":"#/components/schemas/Task"}},"source":{"type":"string","enum":["api_key","session"]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a task","description":"Creates a task. With an API key it is recorded as created by an agent.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCreate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"task":{"$ref":"#/components/schemas/Task"}}}}}},"400":{"description":"Validation failed (details in the body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"description":"Fair-use task ceiling reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"project_id not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/tasks/current":{"get":{"summary":"Task in progress","description":"The task currently in progress, or task: null with a message when there is none.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"task":{"oneOf":[{"$ref":"#/components/schemas/Task"},{"type":"null"}]},"message":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/tasks/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Task id (UUID)","schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Get a task","description":"One task with labels and notes.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"task":{"$ref":"#/components/schemas/Task"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"404":{"description":"Task not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update a task","description":"Change any field. Setting status to blocked should come with blocked_reason; done with completed_summary.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskUpdate"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"task":{"$ref":"#/components/schemas/Task"}}}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"404":{"description":"Task or project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete a task","description":"Deletes the task and its notes and history.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Success"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"404":{"description":"Task not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/tasks/{id}/notes":{"parameters":[{"name":"id","in":"path","required":true,"description":"Task id (UUID)","schema":{"type":"string","format":"uuid"}}],"get":{"summary":"List notes","description":"Notes on a task, oldest first.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"notes":{"type":"array","items":{"$ref":"#/components/schemas/Note"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"404":{"description":"Task not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Add a note","description":"Adds a note to the task.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["content"],"properties":{"content":{"type":"string","minLength":1,"maxLength":5000,"description":"Note text"}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"note":{"$ref":"#/components/schemas/Note"}}}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"404":{"description":"Task not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/projects":{"get":{"summary":"List projects","description":"Projects in the account.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"projects":{"type":"array","items":{"$ref":"#/components/schemas/Project"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a project","description":"Creates a project.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Project name"},"description":{"type":"string","maxLength":500,"description":"Optional description"},"color":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$","description":"Hex color"}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"project":{"$ref":"#/components/schemas/Project"}}}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"description":"Fair-use project ceiling reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/projects/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Project id (UUID)","schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Get a project","description":"One project.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"project":{"$ref":"#/components/schemas/Project"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update a project","description":"Rename, recolor or archive (is_active false) a project.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Project name"},"description":{"type":["string","null"],"maxLength":500,"description":"Description"},"color":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$","description":"Hex color"},"is_active":{"type":"boolean","description":"false archives the project"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"project":{"$ref":"#/components/schemas/Project"}}}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete a project","description":"Deletes the project; its tasks stay, without a project.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Success"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/labels":{"get":{"summary":"List labels","description":"Labels in the account.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"labels":{"type":"array","items":{"$ref":"#/components/schemas/Label"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a label","description":"Creates a label.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":50,"description":"Label name"},"color":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$","description":"Hex color"}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"label":{"$ref":"#/components/schemas/Label"}}}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/summary":{"get":{"summary":"Counts and limits","description":"Task counts by status and the account's fair-use ceilings.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"summary":{"type":"object","description":"Counts by status and priority"},"plan":{"type":"object","description":"Usage and fair-use ceilings"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"An atd_sk_ API key from https://taskhold.com/dashboard/settings (or a setup URL, which creates one for you)."}},"responses":{"Unauthorized":{"description":"Missing, malformed or unknown API key. `reason` is one of missing_key, bad_header, not_a_taskhold_key, unknown_key; `message` says what to do and `url` links to Settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthError"}}}},"SubscriptionRequired":{"description":"The key is valid but the account has no active subscription. `url` links to Billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthError"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"details":{}}},"AuthError":{"type":"object","properties":{"error":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"url":{"type":"string","format":"uri"}}},"Success":{"type":"object","properties":{"success":{"type":"boolean"}}},"Task":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":["string","null"]},"status":{"type":"string","enum":["todo","in_progress","blocked","done"]},"priority":{"type":"string","enum":["low","medium","high","urgent"]},"project_id":{"type":["string","null"],"format":"uuid"},"blocked_reason":{"type":["string","null"]},"completed_summary":{"type":["string","null"]},"created_by":{"type":"string","enum":["human","agent"]},"code_file_path":{"type":["string","null"]},"code_line_number":{"type":["integer","null"]},"labels":{"type":"array","items":{"$ref":"#/components/schemas/Label"}},"notes":{"type":"array","items":{"$ref":"#/components/schemas/Note"}},"completed_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"TaskCreate":{"type":"object","required":["title"],"properties":{"title":{"type":"string","minLength":1,"maxLength":500,"description":"Short task title"},"description":{"type":"string","maxLength":10000,"description":"Details"},"project_id":{"type":["string","null"],"format":"uuid","description":"Project; omit for none"},"priority":{"type":"string","enum":["low","medium","high","urgent"],"default":"medium","description":"Priority"},"status":{"type":"string","enum":["todo","in_progress","blocked","done"],"default":"todo","description":"Initial status"},"labels":{"type":"array","maxItems":20,"items":{"type":"string","maxLength":50},"description":"Label names; created if missing"},"code_file_path":{"type":"string","maxLength":500,"description":"File a TODO came from"},"code_line_number":{"type":"integer","minimum":1,"description":"Line of that TODO"}}},"TaskUpdate":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":500,"description":"Title"},"description":{"type":["string","null"],"maxLength":10000,"description":"Details"},"project_id":{"type":["string","null"],"format":"uuid","description":"Project"},"priority":{"type":"string","enum":["low","medium","high","urgent"],"description":"Priority"},"status":{"type":"string","enum":["todo","in_progress","blocked","done"],"description":"Status"},"blocked_reason":{"type":["string","null"],"maxLength":1000,"description":"Why it is blocked (shown to the person)"},"completed_summary":{"type":["string","null"],"maxLength":5000,"description":"What was done"}}},"Note":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"task_id":{"type":"string","format":"uuid"},"content":{"type":"string"},"created_by":{"type":"string","enum":["human","agent"]},"created_at":{"type":"string","format":"date-time"}}},"Project":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":["string","null"]},"color":{"type":"string"},"is_active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}},"Label":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"color":{"type":"string"}}}}}}