REST API

Routes express product operations, not tables. There is no generic row endpoint, because one pushes every business rule out to the caller.

Two columns, because they are two different things. Permission is what the person or credential must be allowed to do. Token scope is which scopes on an API token can carry that permission, and a token never exceeds the role of whoever created it. Where the scope column says signed in as a person, no token can make the call however it is scoped: paying, administering members, and taking a copy of everything out are things a person does.

Endpoints

Six calls, captured from the running API

Real requests against a real workspace, pasted rather than written. Three of them fail on purpose, because the shape of a refusal is the half you have to write code against and the half nobody publishes.

Authenticate

One header on every call. An API token, or a session or MCP access token issued through AuthKit. Nothing else is read: there is no key in a query string and no cookie the API depends on.

curl https://api.indraft.io/v1/schema \
  -H "Authorization: Bearer $INDRAFT_TOKEN"

Create a company, safely twice

The idempotency key is what makes the call safe to retry. Send the same key with the same input and the second call returns the first result rather than a second company.

curl -X POST https://api.indraft.io/v1/companies:upsert \
  -H "Authorization: Bearer $INDRAFT_TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "name": "Halden Systems",
    "domain": "haldensystems.io",
    "industry": "Logistics software",
    "assertionKind": "imported",
    "attributionLabel": "CRM export",
    "idempotencyKey": "halden-2026-08-25"
  }'

{
  "status": "created",
  "record": {
    "id": "co_01M0XRJKFDV1QPXA9FT3V5K9YK",
    "name": "Halden Systems",
    "domain": "haldensystems.io",
    "domainNormalized": "haldensystems.io",
    "industry": "Logistics software",
    "version": 1,
    "createdAt": "2026-08-26T00:47:29.261Z"
  },
  "mutation": {
    "mutationId": "mut_01M0XRJKFDV1QPXA9FT3V5K9YM",
    "status": "created",
    "matchedBy": null,
    "replayed": false,
    "targetId": "co_01M0XRJKFDV1QPXA9FT3V5K9YK"
  }
}

matchedBy is how identity was decided, and it is null here because nothing was matched: this created a record. On a second call it reads domain, and replayed turns true.

An upsert that refuses to guess

A company with no domain, whose name exactly matches one already there. Nothing is committed and both possibilities come back, because an exact name with no domain is the weakest evidence available: two businesses share a name far more often than they share a domain.

{
  "status": "ambiguous",
  "candidates": [
    {
      "id": "co_01M0XRJKZ9FM7VA4R05FARE42G",
      "label": "Bramley Warehousing",
      "matchedOn": "exact name, no domain supplied"
    }
  ],
  "requestId": "1ac9f764-a031-4e4c-9031-067ffe9752a7"
}

Recover by supplying the domain, by sending the id you meant, or by setting createDistinct when it really is a second company with the same name.

A write that lost a race

Send expectedVersion and the write applies only if the record is still the one you read. This is the answer to two agents editing the same account a second apart.

{
  "code": "stale_version",
  "message": "expectedVersion does not match the current record. Nothing was overwritten.",
  "recoveryHint": "Re-read the current record and apply the intended change again.",
  "requestId": "e80b8e0f-3e0f-4609-bf69-6ef9de9fd530",
  "detail": {
    "currentVersion": 1,
    "expectedVersion": 99
  }
}

Both versions are in the detail, so the decision to re-read and retry or to stop is one your code can make without another request.

A batch where one row fails

Up to a hundred operations in one call. Each is applied independently, so one refusal does not discard the rest, and the result reports every row. The third row here is the ambiguous company from above.

{
  "succeeded": 2,
  "failed": 1,
  "results": [
    {
      "index": 0,
      "operation": "upsert_company",
      "ok": true,
      "result": {
        "status": "created",
        "targetId": "co_01M0XV7D53P2Q4S48VYR2N8V4R"
      }
    },
    {
      "index": 1,
      "operation": "upsert_company",
      "ok": true,
      "result": {
        "status": "created",
        "targetId": "co_01M0XV7D53P2Q4S48VYR2N8V4Y"
      }
    },
    {
      "index": 2,
      "operation": "upsert_company",
      "ok": false,
      "error": {
        "code": "ambiguous_identity",
        "message": "Upsert matched multiple plausible records. Nothing was committed.",
        "candidates": [
          {
            "id": "co_01M0XRJKZ9FM7VA4R05FARE42G",
            "label": "Bramley Warehousing",
            "matchedOn": "exact name, no domain supplied"
          }
        ]
      }
    }
  ]
}

Everything that changed since you last asked

The read an outside copy is built on. Keep the cursor and hand it back; do not parse it. retention says how far back the feed goes, which is the answer to what happens if your job is broken for a fortnight.

curl "https://api.indraft.io/v1/changes?limit=2" \
  -H "Authorization: Bearer $INDRAFT_TOKEN"

{
  "items": [
    {
      "id": "mut_01M0XV7D53P2Q4S48VYR2N8V4Z",
      "operation": "upsert_company",
      "targetType": "company",
      "targetId": "co_01M0XV7D53P2Q4S48VYR2N8V4Y",
      "outcome": "created",
      "accessPath": "rest",
      "assertionKind": "imported",
      "createdAt": "2026-08-26T01:33:48.067Z"
    }
  ],
  "nextCursor": "aWRmYzE6bXV0XzAxTTBYVjdENTNQMlE0UzQ4VllSMk44VjRT",
  "retention": {
    "oldestRetainedAt": "2026-08-26T00:47:29.261Z"
  }
}

Each entry names the operation, the outcome and the route it came in by, so a row your own automation wrote is distinguishable from one a person typed. That is what stops a two-way sync echoing itself forever.

Asking a narrower question

Every list takes filter, which repeats, and sort. A predicate is field:op:value, and every predicate you send must hold. Up to 8 of them.

GET /v1/opportunities
  ?filter=status:eq:open
  &filter=amount_minor:gte:5000000
  &filter=owner_actor_id:eq:act_01J9Z8QK7M4T2VB3XCDEFGHJKM
  &sort=expected_close_date

The comparisons are eq, ne, gt, gte, lt, lte, in, isNull, isNotNull and contains. Sort by a field name for ascending, or prefix it with a minus for descending. The default is newest created first, and every ordering is broken on the record id, so a record cannot appear on two pages or be skipped between them.

Fields your workspace defined on a built-in object are addressed with cf. in front of the key, so a field you happen to call status cannot be confused with the one we ship. Your own object types filter on the fields you declared indexed.

Not everything is filterable, and that is on purpose. A workspace is one database serving one customer, and a query that cannot use an index would hold up every other read and write in it rather than only being slow for you. So a field that would need a full scan is refused, by name, with a list of what you can use instead. Ask GET /v1/schema once and it tells you the whole vocabulary for every object type, including your own. There is no substring match and no OR: keyword matching has its own endpoint, and two narrow calls are predictable where one wide call is sometimes fast.

A cursor from a sorted list remembers the sort it came from. Asking for the next page with a different order is refused rather than answered, because the answer would look complete and quietly be missing records.

Asking for a number instead of records

When the question is how many or how much, ask for the number. The database computes it; nothing summarizes or estimates it, and it does not get slower as your workspace grows the way reading every record and adding them up does.

GET /v1/aggregate
  ?objectType=opportunity
  &function=sum
  &field=amount_minor
  &filter=status:eq:open
  &groupBy=expected_close_date
  &bucket=quarter

The functions are count, sum, avg, min and max. count counts records and takes no field. Filters are the same predicates as above, so an aggregate is a filter plus a reduction rather than a second language.

Grouping is restricted to dimensions that make sense to group by: a stage, a status, an owner, a lifecycle, a tag, or one of your own enum fields. A date must be bucketed to day, week, month, quarter or year, because grouping by a raw timestamp gives you one group per record. GET /v1/schema lists what each object type can be grouped by and reduced.

An answer with more than 200 groups is refused, not shortened. A truncated total reads exactly like a real one and you would have no way to tell, which is the one mistake this product is built not to make. Narrow it with a filter, or group by something coarser.

What we will and will not change

The /v1 in the path is a namespace, not a stability promise, and it would be dishonest to let it read as one before we have customers to keep it for. Until general availability this API can change in ways that break a caller, and when it does we will say so here.

Four things are already frozen and will not change quietly, because they are what your error handling and your identifiers are built on: the error codes, the identifier prefix for every object type, the built-in object types, and the webhook event names. Each is published as a fixed list in the document above, so you can generate against it rather than copy it.

There is no deprecation window yet. Saying that plainly is more use to you than implying one we have not committed to.

Limits

Published as numbers so you can size a scheduler before you write one. Two mechanisms, and the difference decides your recovery: infrastructure protection returns rate_limited, which means wait, and a product limit returns quota_exceeded or workspace_capacity, where retrying the same call unchanged can never succeed. Plan quotas are separate again and are on the pricing page.

Every response carries ratelimit-limit, ratelimit-remaining and ratelimit-reset for the window closest to refusing you, and ratelimit-policy lists them all. A refusal adds retry-after in seconds. Read them on the way past and you never have to discover a limit by being refused.

Errors

Every failure carries a stable code and a recovery hint written for an agent rather than for a human reading a log. An agent's error handling is only as good as this contract: if it cannot tell an ambiguous identity from a duplicate one, every failure degrades to a blind retry or a give-up.