Developer docs

Flatgrin API

Build automations, syncs, and internal tools against the Flatgrin REST API. All endpoints return JSON over HTTPS.

Base URL

https://api.flatgrin.online/v1

All paths below are relative to this base URL.

Authentication

Authenticate with a Bearer token issued from your workspace settings under Settings → API. Pass the token in the Authorization header on every request.

curl https://api.flatgrin.online/v1/tasks \
  -H "Authorization: Bearer fg_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

Rate limits

Plan	Requests / minute	Burst
Starter	60	100
Growth	180	300
Enterprise	Custom	Custom

Responses include X-RateLimit-Remaining and X-RateLimit-Reset headers. Exceeding limits returns HTTP 429.

Endpoints

GET /tasks

List tasks in the workspace. Filter by project, assignee, or status.

curl "https://api.flatgrin.online/v1/tasks?status=active&limit=20" \
  -H "Authorization: Bearer fg_live_xxxxxxxxxxxxxxxx"

Example response

{
  "data": [
    {
      "id": "tsk_9f2a1c",
      "title": "Finalize onboarding checklist",
      "status": "in_progress",
      "assignee_id": "usr_3b11",
      "project_id": "prj_88d0",
      "due_date": "2026-07-15",
      "priority": "high",
      "created_at": "2026-06-01T14:22:00Z"
    }
  ],
  "meta": { "total": 142, "limit": 20, "offset": 0 }
}

GET /tasks/:id

Retrieve a single task by ID, including description and linked resources.

curl https://api.flatgrin.online/v1/tasks/tsk_9f2a1c \
  -H "Authorization: Bearer fg_live_xxxxxxxxxxxxxxxx"

Example response

{
  "id": "tsk_9f2a1c",
  "title": "Finalize onboarding checklist",
  "description": "Update steps for new hire week one.",
  "status": "in_progress",
  "assignee_id": "usr_3b11",
  "project_id": "prj_88d0",
  "due_date": "2026-07-15",
  "priority": "high",
  "labels": ["ops", "hr"],
  "created_at": "2026-06-01T14:22:00Z",
  "updated_at": "2026-06-18T09:10:00Z"
}

POST /tasks

Create a task. Required fields: title and project_id.

curl -X POST https://api.flatgrin.online/v1/tasks \
  -H "Authorization: Bearer fg_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Ship Q3 release notes",
    "project_id": "prj_88d0",
    "assignee_id": "usr_3b11",
    "due_date": "2026-07-20",
    "priority": "medium"
  }'

Example response

{
  "id": "tsk_a4e01f",
  "title": "Ship Q3 release notes",
  "status": "todo",
  "project_id": "prj_88d0",
  "assignee_id": "usr_3b11",
  "due_date": "2026-07-20",
  "priority": "medium",
  "created_at": "2026-06-20T16:05:00Z"
}

GET /projects

List projects with progress summaries for reporting dashboards.

curl https://api.flatgrin.online/v1/projects \
  -H "Authorization: Bearer fg_live_xxxxxxxxxxxxxxxx"

Example response

{
  "data": [
    {
      "id": "prj_88d0",
      "name": "Q3 Product Launch",
      "status": "active",
      "progress_pct": 62,
      "task_counts": { "todo": 18, "in_progress": 24, "done": 69 },
      "on_time_rate": 0.91
    }
  ]
}

POST /tasks/:id/comments

Add a comment to a task. Mentions use the form @user_id.

curl -X POST https://api.flatgrin.online/v1/tasks/tsk_9f2a1c/comments \
  -H "Authorization: Bearer fg_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Checklist reviewed. @usr_3b11 can you confirm HR sign-off?"
  }'

Example response

{
  "id": "cmt_71bc",
  "task_id": "tsk_9f2a1c",
  "body": "Checklist reviewed. @usr_3b11 can you confirm HR sign-off?",
  "author_id": "usr_aa02",
  "created_at": "2026-06-20T16:12:00Z"
}

Errors

Errors return a consistent JSON body:

{
  "error": {
    "code": "not_found",
    "message": "Task tsk_missing was not found",
    "request_id": "req_0f8e2a"
  }
}

SDKs & libraries

Official and community libraries help you integrate faster. Install from your package manager and pass the same API key used with curl.

Node.js / TypeScript

npm package @flatgrin/sdk for server and edge runtimes.

npm install @flatgrin/sdk

Python

PyPI package flatgrin with async and sync clients.

pip install flatgrin

Go

Module for backend services and CLI tooling.

go get github.com/flatgrin/flatgrin-go

Webhooks

Subscribe to task.created, task.updated, and project.completed events from workspace settings.

Need higher limits or private endpoints?

Enterprise customers can request dedicated rate tiers and sandbox workspaces.