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

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.