API reference · gantt-chart.io

Authentication

Create a key in Settings → Account → API Keys, then send it on every request:

Authorization: Bearer gk_your_key

Keys have full read and write access to your account; keep them secret and revoke any you no longer use. Each key has a monthly quota (1,000 calls by default) that resets on the 1st of the month, UTC. Over the quota the API answers 429. Task start and duration are whole days counted from the project's day 0 — its startDate (returned by GET /api/v1/projects).

Machine-readable spec: /openapi.json (OpenAPI 3.1). Base URL: https://gantt-chart.io.

Endpoints

GET /api/v1/projects — List projects
GET /api/v1/projects/{id}/tasks — List a project's tasks
POST /api/v1/projects/{id}/tasks — Add a task
PATCH /api/v1/tasks/{id} — Update a task
POST /api/v1/timeline — Generate a timeline from a prompt
GET /api/v1/webhooks — List webhooks
POST /api/v1/webhooks — Register a webhook
DELETE /api/v1/webhooks/{id} — Remove a webhook

`GET /api/v1/projects`

List projects. Your projects, most recently updated first. Trashed projects are excluded.

Responses

200 OK
401 Missing, invalid or revoked API key.
429 Monthly quota for this key is used up (resets on the 1st, UTC).

`GET /api/v1/projects/{id}/tasks`

List a project's tasks.

Path: {id} — Project id (from GET /api/v1/projects).

Responses

200 OK
401 Missing, invalid or revoked API key.
404 No such project on your account.
429 Monthly quota for this key is used up (resets on the 1st, UTC).

`POST /api/v1/projects/{id}/tasks`

Add a task. Creates a task and sends task.created to your webhooks.

Path: {id} — Project id (from GET /api/v1/projects).

Request body (JSON)

Field	Type	Notes
`title` (required)	`string`	Trimmed to 120 characters.
`lane`	`string`	Default "General".
`start`	`integer`	Days from project day 0 (start_date is accepted too) Default 0.
`duration`	`integer`	Days (at least 1); missing becomes 5. Default 5.
`status`	`"On track" \| "At risk" \| "Done"`
`assignee`	`string`
`description`	`string`	Trimmed to 4,000 characters.

Responses

201 Created
400 Invalid JSON or missing title.
401 Missing, invalid or revoked API key.
404 No such project on your account.
429 Monthly quota for this key is used up (resets on the 1st, UTC).

`PATCH /api/v1/tasks/{id}`

Update a task. Updates only the fields you send and sends task.updated to your webhooks.

Path: {id}

Request body (JSON)

Field	Type	Notes
`title`	`string`
`status`	`"On track" \| "At risk" \| "Done"`
`progress`	`integer`	Clamped to 0–100.
`start`	`integer`	Negative values become 0.
`duration`	`integer`	Values below 1 become 1.
`assignee`	`string`

Responses

200 OK
400 Invalid id or JSON.
401 Missing, invalid or revoked API key.
404 No such task on your account.
429 Monthly quota for this key is used up (resets on the 1st, UTC).

`POST /api/v1/timeline`

Generate a timeline from a prompt. Returns AI-drafted timeline items. Nothing is saved; add the items you want with POST /api/v1/projects/{id}/tasks.

Request body (JSON)

Field	Type	Notes
`prompt` (required)	`string`	Up to 4,000 characters.
`lanes`	`string[]`	The first 10 are used.

Responses

200 OK
400 Invalid JSON, or a missing or too-long prompt.
401 Missing, invalid or revoked API key.
429 Monthly quota for this key is used up (resets on the 1st, UTC).
502 The AI service failed; retry.
503 AI generation is not configured.

`GET /api/v1/webhooks`

List webhooks.

Responses

200 OK
401 Missing, invalid or revoked API key.
429 Monthly quota for this key is used up (resets on the 1st, UTC).

`POST /api/v1/webhooks`

Request body (JSON)

Field	Type	Notes
`url` (required)	`string`	https:// only
`events`	`("task.created" \| "task.updated")[]`	Default ["task.created","task.updated"].

Responses

201 Created
400 URL is not https:// or JSON is invalid.
401 Missing, invalid or revoked API key.
429 Monthly quota for this key is used up (resets on the 1st, UTC).

`DELETE /api/v1/webhooks/{id}`

Remove a webhook. Deactivates the webhook. Unknown ids also answer deleted: true.

Path: {id}

Responses

200 OK
401 Missing, invalid or revoked API key.
429 Monthly quota for this key is used up (resets on the 1st, UTC).

Example

With your key in the GANTT_API_KEY environment variable:

curl https://gantt-chart.io/api/v1/projects \
  -H "Authorization: Bearer $GANTT_API_KEY"

curl -X POST https://gantt-chart.io/api/v1/projects/PROJECT_ID/tasks \
  -H "Authorization: Bearer $GANTT_API_KEY" -H "Content-Type: application/json" \
  -d '{"title":"Security review","lane":"Engineering","start":14,"duration":3}'

Webhooks

Register an https:// URL with POST /api/v1/webhooks and choose events (task.created, task.updated). Each delivery is a JSON POST of { "event", "data": <task>, "ts" } with an X-Gantt-Signature: sha256=… header: the hex HMAC-SHA256 of the raw request body, keyed with the secret returned when you registered the webhook. Webhooks fire for tasks created or updated through this API (not for edits in the web app), with one attempt and a 5-second timeout.

// Node.js
import { createHmac, timingSafeEqual } from "node:crypto";
const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
const received = String(req.headers["x-gantt-signature"] ?? "");
const ok = received.length === expected.length && timingSafeEqual(Buffer.from(received), Buffer.from(expected));

Questions or a missing endpoint? Contact us.