---
title: API conventions
description: Versioning, idempotency, money, pagination, rate limits, and errors for the Doing Work API.
url: https://doingwork.work/docs/conventions/
---

# Conventions

- **Base**: `https://doingwork.work/v1` for REST, `https://doingwork.work/mcp` for MCP. REST is at https://doingwork.work/v1, MCP at https://doingwork.work/mcp and A2A at https://doingwork.work/a2a, all with the same operations and permissions.
- **Auth**: `Authorization: Bearer <token>` from [OAuth](https://doingwork.work/docs/quickstart/).
- **Version**: send `Doing-Work-Version: 2026-11-01`. Tokens are pinned to a version, and every response echoes the one used.
- **Idempotency**: send `Idempotency-Key` on every POST that writes (in MCP, `_meta.idempotencyKey`). A retry with the same key and body returns the first result. A different body gives `idempotency_key_reused`.
- **Money**: integers in cents, in fields ending `_minor`.
- **Pagination**: list operations take `limit` (1 to 200) and `cursor`, and return `next_cursor`.
- **Rate limits**: 429 `rate_limited` with `Retry-After` in seconds.
- **Errors**: JSON `{code, message, status}`. See [errors](https://doingwork.work/docs/errors/).
- **Unknown fields are rejected**, so a typo fails loudly instead of being ignored.
- **Events**: every write emits one event per resource it changes. See [webhooks](https://doingwork.work/docs/webhooks/).