{"openapi":"3.1.0","info":{"title":"gantt-chart.io API","version":"1","description":"Read and update your gantt-chart.io projects, add tasks, generate a timeline from a prompt, and receive webhooks. Authenticate with an API key from Settings → Account → API Keys: `Authorization: Bearer gk_…`. Each key has a monthly quota (1,000 calls by default, every authenticated call counts) that resets on the 1st of each month (UTC). Task `start` and `duration` are whole days counted from the project's day 0, which is the project's `startDate`."},"servers":[{"url":"https://gantt-chart.io"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key, e.g. gk_3f9…"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"Status":{"type":"string","enum":["On track","At risk","Done"]},"Project":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"icon":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"startDate":{"type":["string","null"],"format":"date","description":"Calendar date of day 0 (YYYY-MM-DD); null until the project is first opened"}}},"Task":{"type":"object","properties":{"id":{"type":"integer"},"projectId":{"type":"string"},"title":{"type":"string"},"lane":{"type":"string"},"start":{"type":"integer","description":"Days from project day 0"},"duration":{"type":"integer","description":"Days (minimum 1)"},"progress":{"type":"integer","minimum":0,"maximum":100},"status":{"$ref":"#/components/schemas/Status"},"assignee":{"type":"string"},"description":{"type":"string"},"source":{"type":"string"},"parent":{"type":"string"},"dependsOn":{"type":"string","description":"Comma-separated task ids"},"tags":{"type":"string","description":"Comma-separated"},"eventType":{"type":"string","description":"Task, Milestone, …"},"color":{"type":"string"},"icon":{"type":"string"},"locked":{"type":"boolean"},"hidden":{"type":"boolean"},"ownerEmail":{"type":"string","description":"Your account email"},"updatedAt":{"type":"string","format":"date-time"}}},"TimelineItem":{"type":"object","properties":{"title":{"type":"string"},"lane":{"type":"string"},"start":{"type":"integer"},"duration":{"type":"integer"},"progress":{"type":"integer"},"status":{"$ref":"#/components/schemas/Status"},"owner":{"type":"string"},"source":{"type":"string"},"parent":{"type":"string"}}},"Webhook":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"events":{"type":"string","description":"Comma-separated: task.created, task.updated"},"active":{"type":"boolean"},"createdAt":{"type":"integer","description":"Unix ms"}}},"WebhookPayload":{"type":"object","description":"POSTed to your URL when a task is created or updated through this API (edits in the web app do not send webhooks). One attempt, 5-second timeout, no retries. Verify X-Gantt-Signature: sha256=<hex HMAC-SHA256 of the raw body, keyed with the webhook secret>.","properties":{"event":{"type":"string","enum":["task.created","task.updated"]},"data":{"$ref":"#/components/schemas/Task"},"ts":{"type":"integer"}}}}},"paths":{"/api/v1/projects":{"get":{"summary":"List projects","description":"Your projects, most recently updated first. Trashed projects are excluded.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"projects":{"type":"array","items":{"$ref":"#/components/schemas/Project"}}}}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Monthly quota for this key is used up (resets on the 1st, UTC).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/projects/{id}/tasks":{"get":{"summary":"List a project's tasks","parameters":[{"name":"id","in":"path","required":true,"description":"Project id (from GET /api/v1/projects).","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"tasks":{"type":"array","items":{"$ref":"#/components/schemas/Task"}}}}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such project on your account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Monthly quota for this key is used up (resets on the 1st, UTC).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Add a task","description":"Creates a task and sends task.created to your webhooks.","parameters":[{"name":"id","in":"path","required":true,"description":"Project id (from GET /api/v1/projects).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title"],"properties":{"title":{"type":"string","description":"Trimmed to 120 characters."},"lane":{"type":"string","default":"General"},"start":{"type":"integer","default":0,"description":"Days from project day 0 (start_date is accepted too)"},"duration":{"type":"integer","default":5,"description":"Days (at least 1); missing becomes 5."},"status":{"$ref":"#/components/schemas/Status"},"assignee":{"type":"string"},"description":{"type":"string","description":"Trimmed to 4,000 characters."}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"task":{"$ref":"#/components/schemas/Task"}}}}}},"400":{"description":"Invalid JSON or missing title.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such project on your account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Monthly quota for this key is used up (resets on the 1st, UTC).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/tasks/{id}":{"patch":{"summary":"Update a task","description":"Updates only the fields you send and sends task.updated to your webhooks.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"status":{"$ref":"#/components/schemas/Status"},"progress":{"type":"integer","description":"Clamped to 0–100."},"start":{"type":"integer","description":"Negative values become 0."},"duration":{"type":"integer","description":"Values below 1 become 1."},"assignee":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"task":{"$ref":"#/components/schemas/Task"}}}}}},"400":{"description":"Invalid id or JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such task on your account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Monthly quota for this key is used up (resets on the 1st, UTC).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/timeline":{"post":{"summary":"Generate a timeline from a prompt","description":"Returns AI-drafted timeline items. Nothing is saved; add the items you want with POST /api/v1/projects/{id}/tasks.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string","description":"Up to 4,000 characters."},"lanes":{"type":"array","items":{"type":"string"},"description":"The first 10 are used."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"items":{"type":"array","items":{"$ref":"#/components/schemas/TimelineItem"}}}}}}},"400":{"description":"Invalid JSON, or a missing or too-long prompt.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Monthly quota for this key is used up (resets on the 1st, UTC).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The AI service failed; retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"AI generation is not configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/webhooks":{"get":{"summary":"List webhooks","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"webhooks":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}}}}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Monthly quota for this key is used up (resets on the 1st, UTC).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Register a webhook","description":"The response includes the signing secret once; store it to verify X-Gantt-Signature.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"https:// only"},"events":{"type":"array","items":{"type":"string","enum":["task.created","task.updated"]},"default":["task.created","task.updated"]}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"events":{"type":"string"},"secret":{"type":"string"}}}}}},"400":{"description":"URL is not https:// or JSON is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Monthly quota for this key is used up (resets on the 1st, UTC).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/webhooks/{id}":{"delete":{"summary":"Remove a webhook","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"description":"Deactivates the webhook. Unknown ids also answer deleted: true.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"}}}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Monthly quota for this key is used up (resets on the 1st, UTC).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}