# Checklist API

Complete a checklist item from your server.

For checklist items of type **API**: your server reports that the user did something, such as verifying their account or paying.

### `POST https://guidemark.co/api/checklist/complete-item`

```bash
curl -X POST https://guidemark.co/api/checklist/complete-item \
  -H "Authorization: Bearer gm_…" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"…","checklistId":"…","itemId":"…","userId":"user_123"}'
```

| Field         | Type   | Notes                                                                                                           |
| ------------- | ------ | --------------------------------------------------------------------------------------------------------------- |
| `projectId`   | UUID   | Your project                                                                                                    |
| `checklistId` | UUID   | The checklist                                                                                                   |
| `itemId`      | UUID   | The item to complete                                                                                            |
| `userId`      | string | The same ID you pass to [`ProductTour.identify`](/docs/reference/javascript-api#identify), up to 255 characters |

Responses: `200 { "success": true }`; `400` for missing or malformed fields; `401` for a missing, invalid or revoked key; `403` if the key belongs to another project or lacks `write_drafts`; `429` over the rate limit.

## The key

Use an agent [API key](/docs/agents/api-keys): in **Settings → Agents**, click **API key** and name it after the server that will call this endpoint (for example "Billing webhooks"). It doesn't need **Can publish**. Copy it when it's shown, since it's displayed once, and keep it on your server: never in front-end code, because anyone holding it could complete items for any user.

The key must belong to the project in `projectId` and have the `write_drafts` scope, which every key has. Calls here count toward the key's limit of 60 requests per minute; over that you get `429` with `Retry-After`.

Revoking the key in Settings → Agents stops it working here too.

<Callout title="Older checklist keys">
  Project checklist keys issued before agent API keys existed still work. New integrations should use an agent API key, which you can see, revoke and replace yourself.
</Callout>