# craftivo Public API

> REST API for craft businesses: customers, projects, tasks, time entries, documents, forms, members and webhooks.

Production API: https://quick-goldfinch-475.eu-west-1.convex.site
Website: https://www.craftivo.app

## Essentials

- Authentication: send `Authorization: Bearer <API key>`. The organization owner creates keys in the app under Settings (Einstellungen) → API & Webhooks. API access is included in the Business plan; Starter and Premium need the „Schnittstelle“ add-on (booked in Settings → Abo & Abrechnung). `GET /api/v1/me` works on every plan.
- Organization: keys from the settings are bound to one organization. A key with access to several organizations must send `X-Organization-Id`; otherwise the API answers 400 `organization_required`.
- Call the API from a server or a terminal, never from browser JavaScript: API v1 sends no CORS headers, and the key must stay secret.
- Envelope: success is `{ "data": … }`; lists add `{ "meta": { "cursor", "isDone", "limit" } }`. Errors are `{ "error": { "code", "message", "details"? } }`.
- Pagination: pass `meta.cursor` as `cursor` until `meta.isDone` is true. `limit` is 1–100, default 50. Lists are sorted newest first.
- Scopes: `read` allows only GET; `read_write` allows writes. Webhook management works with both.
- Writes: `POST` and `PUT` accept an `Idempotency-Key` header; a repeated key from the same API key on the same method and path replays the stored 2xx response for 30 days. Another API key with the same value runs as a new request. Every replay checks the current permissions first (403 without them).
- Rate limits: exceeding a limit returns 429 `rate_limited` with `Retry-After` in seconds.
- Changes: subscribe to webhooks instead of polling, and catch up after an outage with the `updatedAfter` list filter.
- Schemas: the OpenAPI specification below is the full contract. The OpenAPI download is public and needs no key.

## Documentation

- [Overview](https://www.craftivo.app/developers): Start with the craftivo Public API.
- [Quickstart](https://www.craftivo.app/developers/quickstart): Create a key and make your first authenticated request.
- [API reference](https://www.craftivo.app/developers/reference): Explore every resource, operation, request and response schema.
- [Authentication](https://www.craftivo.app/developers/authentication): Understand API keys, organization selection and scopes.
- [Webhooks](https://www.craftivo.app/developers/webhooks): Subscribe to events and verify every delivery signature.
- [Errors & conventions](https://www.craftivo.app/developers/errors): Handle envelopes, status codes, pagination, dates and money.
- [API changelog](https://www.craftivo.app/developers/changelog): Track contract changes that can affect your integration.

## Specification

- [OpenAPI JSON](https://quick-goldfinch-475.eu-west-1.convex.site/api/v1/openapi.json): Download the complete OpenAPI 3.1 contract. Its server address always points to production.