Quickstart

Make your first request

Create a read-only key, discover its organization, and fetch the first page of customers. The entire flow takes a few minutes.

API access requires the Business plan. Only the organization owner can create or revoke keys in craftivo.

1. Create an API key

Open craftivo, select the organization settings, and go to API & Webhooks → API-Schlüssel. Create a key with the Nur lesen — Daten abrufen scope and copy it immediately. The full key is shown once.

Open organization settings

2. Store the key locally

Keep the key in a secret manager or environment variable. Never put it in browser code, logs, source control, screenshots, or support messages.

Terminal

export CRAFTIVO_API_KEY="msk_…"

3. Discover the organization

Call GET /api/v1/me first. It needs no organization header and returns every organization the key can access.

curl

curl --request GET \
  --url "https://quick-goldfinch-475.eu-west-1.convex.site/api/v1/me" \
  --header "Authorization: Bearer $CRAFTIVO_API_KEY"

200 response

{
  "data": {
    "id": "user_…",
    "createdAt": "2026-01-05T09:00:00.000Z",
    "updatedAt": "2026-08-01T06:00:00.000Z",
    "organizations": [
      {
        "id": "…",
        "organizationId": "org_…",
        "role": "owner",
        "memberType": "office",
        "joinedAt": "2026-01-05T09:00:00.000Z"
      }
    ]
  }
}

4. Fetch customers

Use the returned organization ID for organization-scoped endpoints. This example asks for at most ten customers and returns the standard list envelope.

curl

export CRAFTIVO_ORGANIZATION_ID="org_…"

curl --request GET \
  --url "https://quick-goldfinch-475.eu-west-1.convex.site/api/v1/customers?limit=10" \
  --header "Authorization: Bearer $CRAFTIVO_API_KEY" \
  --header "X-Organization-Id: $CRAFTIVO_ORGANIZATION_ID"

200 response with no matching customers

{
  "data": [],
  "meta": {
    "cursor": "",
    "isDone": true,
    "limit": 10
  }
}

5. Continue with the reference

The API reference contains every available resource, parameter, schema, and error response. Requests that create or update data should use an idempotency key.

Open the API reference