# API documentation

The GetItDone public REST API — authentication, quickstart, errors, rate limits, pagination, idempotency, and webhooks.

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](/docs/api-reference), generated from the OpenAPI document.

## Base URL

```text
https://app.nowgetitdone.com/v1
```

## Quickstart — first 200

1. Create an API key in the app: [Profile → API Keys](https://app.nowgetitdone.com/settings/api-keys).
   It is shown once — store it as a server-side secret.
2. Call the API with your key:

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

A successful list returns a cursor envelope:

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

## Authentication

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

```text
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.

## Errors

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.

```json
{
    "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 →](/docs/api/problems)

## Rate limits & quotas

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.

| Plan | API calls / period | Burst / minute |
| ---- | ------------------ | -------------- |
| Free | 50                 | 10             |
| Pro  | 50,000             | 120            |
| Team | 500,000            | 300            |

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

## Pagination

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`.

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

## Idempotency

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`.

## Webhooks

Receive signed events when tasks change. Full details — event catalog,
signature verification, retries, and secret rotation — on the
[webhooks page](/docs/api/webhooks).

## Keep exploring

- [API reference](/docs/api-reference) — every operation, generated from the OpenAPI document.
- [Error codes](/docs/api/problems) — every problem code, what it means, how to fix it.
- [OpenAPI document](/docs/api/openapi.json) — the OpenAPI 3.1 spec for the whole `/v1` surface.
- [For AI agents](/docs/ai) — machine-readable indexes, Markdown twins, and agent guidelines.
- [TypeScript SDK](https://github.com/DevinoSolutions/getitdone-sdk) — typed client, published on npm: `npm install @nowgetitdone/sdk`.

Prefer AI tooling? Connect the [MCP server](/docs/connecting-ai-assistants) at
`https://app.nowgetitdone.com/api/mcp`.