REST API quickstart, auth and errors

The GetItDone REST API is AI-native task management for people and agents. One gid_ key, Bearer auth, RFC 9457 errors. Every operation is listed in the API reference, generated from the OpenAPI document.

Base URLCopy Anchor Link

https://app.nowgetitdone.com/v1

Quickstart — first 200Copy Anchor Link

1. Create an API key in the app: Profile → API Keys. It is shown once — store it as a server-side secret.
2. Call the API with your key:

curl https://app.nowgetitdone.com/v1/organizations \
  -H "Authorization: Bearer gid_YOUR_API_KEY"

A successful list returns a cursor envelope:

{
    "data": [{ "id": "org_a1b2c3", "name": "Acme Inc", "role": "owner" }],
    "has_more": false,
    "next_cursor": null
}

AuthenticationCopy Anchor Link

Send your key on every request. The bearer header is the only form /v1 accepts — any other header answers 401 missing_credentials:

Authorization: Bearer gid_YOUR_API_KEY

Keys are minted in-app (Profile → API Keys) and shown once. Test keys are prefixed gid_test_ — use them against test data, live keys against production.

ErrorsCopy Anchor Link

Errors are RFC 9457 application/problem+json documents with a stable machine-readable code. Switch on code, never on the human-readable title. Every response carries an x-request-id — quote it in support requests.

{
    "type": "https://nowgetitdone.com/docs/api/problems/validation-failed",
    "title": "Request validation failed",
    "status": 400,
    "code": "validation_failed",
    "request_id": "req_a1b2c3d4",
    "errors": [
        {
            "pointer": "/title",
            "code": "too_small",
            "message": "String must contain at least 1 character(s)"
        }
    ]
}

Browse every error code →

Rate limits & quotasCopy Anchor Link

Two independent systems, two codes. A per-credential burst window answers 429 rate_limited (retry after Retry-After); the billing-period allowance answers 429 quota_exhausted. Every response carries IETF draft-11 RateLimit / RateLimit-Policy headers plus the X-RateLimit-Limit / -Remaining / -Reset trio.

One API call = one request against your workspace quota; it resets each billing period. Outbound webhooks require a Pro or Team plan.

PaginationCopy Anchor Link

List endpoints return a cursor envelope. Pass next_cursor back as the after query parameter for the next page. Filters are baked into the cursor — reusing one with different filters answers 400 validation_failed.

{
    "data": [
        /* … */
    ],
    "has_more": true,
    "next_cursor": "eyJ…"
}

IdempotencyCopy Anchor Link

Consequential POSTs accept an optional Idempotency-Key header (1–255 characters; a UUID works). Retrying with the same key and byte-identical body within 24h replays the stored response — never re-executed, never re-charged. A different body answers 422 idempotency_key_reused; a retry racing the first answers 409 idempotency_in_progress.

WebhooksCopy Anchor Link

Receive signed events when tasks change. Full details — event catalog, signature verification, retries, and secret rotation — on the webhooks page.

Keep exploringCopy Anchor Link

• API reference — every operation, generated from the OpenAPI document.
• Error codes — every problem code, what it means, how to fix it.
• OpenAPI document — the OpenAPI 3.1 spec for the whole /v1 surface.
• For AI agents — machine-readable indexes, Markdown twins, and agent guidelines.
• TypeScript SDK — typed client, published on npm: npm install @nowgetitdone/sdk.

Prefer AI tooling? Connect the MCP server at https://app.nowgetitdone.com/api/mcp.