Gantrel REST API
Base URL /api/v1 · Authenticate with Authorization: Bearer gt_… · OpenAPI 3.1 JSON · Webhook events
Response headers
X-Request-Id- Unique id of the call; shown in Developers → Logs.
X-RateLimit-Limit- Calls allowed per minute for this key.
X-RateLimit-Remaining- Calls left in the current minute.
X-RateLimit-Reset- Unix time when the window resets.
Retry-After- Seconds to wait (only on 429).
Scopes
read | Every GET route |
write | Every POST, PATCH, PUT and DELETE route |
* | Everything (owners only) |
notes:read | GET /notes, GET /notes/:id, GET /checklists |
notes:write | POST /notes, PATCH /notes/:id, DELETE /notes/:id, POST /checklists |
Errors
| 400 | invalid_json | The body is not valid JSON. |
| 401 | unauthenticated | The key is missing, malformed, revoked, or its creator lost access. |
| 401 | key_expired | The key passed its expiry date. Create or rotate a key. |
| 401 | key_rotated | The key was rotated and its overlap window has ended. Use the new key. |
| 403 | scope_missing | The key lacks the scope this route needs. |
| 403 | ip_not_allowed | The key has an IP allowlist and the request came from another address. |
| 403 | feature_disabled | The feature is not enabled for this workspace plan. |
| 404 | not_found | The record does not exist in this workspace. |
| 422 | validation_failed | The query or body failed validation. `details` lists each issue. |
| 429 | rate_limited | Too many requests: wait `Retry-After` seconds. |
| 429 | quota_exceeded | The monthly API quota of the plan is used up. |
| 500 | server_error | Something went wrong on our side. Quote the X-Request-Id header to support. |
get
/api/v1/notesscope: notes:readList notes (cursor pagination)
Parameters: q (query), tag (query), pinned (query), limit (query), cursor (query)
curl -X GET "https://gantrel-nextjs.vercel.app/api/v1/notes?limit=<limit>" \
-H "Authorization: Bearer $GANTREL_API_KEY"post
/api/v1/notesscope: notes:writeCreate a note
curl -X POST "https://gantrel-nextjs.vercel.app/api/v1/notes" \
-H "Authorization: Bearer $GANTREL_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "title": "string", "body": "", "tags": [], "pinned": false, "dueAt": null }'{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"title": {
"type": "string",
"minLength": 1,
"maxLength": 140
},
"body": {
"default": "",
"type": "string",
"maxLength": 20000
},
"tags": {
"default": [],
"maxItems": 10,
"type": "array",
"items": {
"type": "string",
"pattern": "^[a-z0-9-]{1,24}$"
}
},
"pinned": {
"default": false,
"type": "boolean"
},
"dueAt": {
"default": null,
"anyOf": [
{},
{
"type": "null"
}
]
}
},
"required": [
"title",
"body",
"tags",
"pinned",
"dueAt"
],
"additionalProperties": false
}get
/api/v1/notes/{id}scope: notes:readGet a note
Parameters: id (path)
curl -X GET "https://gantrel-nextjs.vercel.app/api/v1/notes/<id>" \
-H "Authorization: Bearer $GANTREL_API_KEY"patch
/api/v1/notes/{id}scope: notes:writeUpdate a note
Parameters: id (path)
curl -X PATCH "https://gantrel-nextjs.vercel.app/api/v1/notes/<id>" \
-H "Authorization: Bearer $GANTREL_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "title": "string", "body": "", "tags": [], "pinned": false, "dueAt": null }'{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"title": {
"type": "string",
"minLength": 1,
"maxLength": 140
},
"body": {
"default": "",
"type": "string",
"maxLength": 20000
},
"tags": {
"default": [],
"maxItems": 10,
"type": "array",
"items": {
"type": "string",
"pattern": "^[a-z0-9-]{1,24}$"
}
},
"pinned": {
"default": false,
"type": "boolean"
},
"dueAt": {
"default": null,
"anyOf": [
{},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}delete
/api/v1/notes/{id}scope: notes:writeDelete a note
Parameters: id (path)
curl -X DELETE "https://gantrel-nextjs.vercel.app/api/v1/notes/<id>" \
-H "Authorization: Bearer $GANTREL_API_KEY"get
/api/v1/checklistsscope: notes:readList checklists (needs the checklists feature)
curl -X GET "https://gantrel-nextjs.vercel.app/api/v1/checklists" \
-H "Authorization: Bearer $GANTREL_API_KEY"post
/api/v1/checklistsscope: notes:writeCreate a checklist
curl -X POST "https://gantrel-nextjs.vercel.app/api/v1/checklists" \
-H "Authorization: Bearer $GANTREL_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "title": "string" }'{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"title": {
"type": "string",
"minLength": 1,
"maxLength": 140
}
},
"required": [
"title"
],
"additionalProperties": false
}get
/api/v1/mescope: readThe organisation this key belongs to
curl -X GET "https://gantrel-nextjs.vercel.app/api/v1/me" \
-H "Authorization: Bearer $GANTREL_API_KEY"get
/api/v1/membersscope: readList members
Parameters: role (query)
curl -X GET "https://gantrel-nextjs.vercel.app/api/v1/members" \
-H "Authorization: Bearer $GANTREL_API_KEY"get
/api/v1/usagescope: readUsage for the current billing period
curl -X GET "https://gantrel-nextjs.vercel.app/api/v1/usage" \
-H "Authorization: Bearer $GANTREL_API_KEY"post
/api/v1/eventsscope: writeRecord a metered usage event
curl -X POST "https://gantrel-nextjs.vercel.app/api/v1/events" \
-H "Authorization: Bearer $GANTREL_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "metric": "string", "quantity": 1 }'{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"metric": {
"type": "string",
"pattern": "^[a-z0-9._-]+$"
},
"quantity": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 1000000
}
},
"required": [
"metric",
"quantity"
],
"additionalProperties": false
}post
/api/v1/ai/completescope: writeGenerate text with the configured AI driver
curl -X POST "https://gantrel-nextjs.vercel.app/api/v1/ai/complete" \
-H "Authorization: Bearer $GANTREL_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "prompt": "string" }'{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"prompt": {
"type": "string",
"minLength": 1,
"maxLength": 4000
},
"system": {
"type": "string",
"maxLength": 2000
}
},
"required": [
"prompt"
],
"additionalProperties": false
}get
/api/v1/featuresscope: readFeature flags and whether each is on for this organisation
curl -X GET "https://gantrel-nextjs.vercel.app/api/v1/features" \
-H "Authorization: Bearer $GANTREL_API_KEY"