Limits

Everything on this page is a scope statement, not a rough edge to route around. Read it before you design an integration.

v1 is supervised-only

mode: "autonomous", mode: "fast" and publication.policy: "auto" return 501. The only build this API serves today is a supervised one.

An unattended build sets a switch that does not merely suppress questions — it turns the gate machinery off, and the publish-review gate is part of that machinery. That gate is the step that opens the pull request and registers the delivery subscription. So an unattended build here would run all the way to a validated feed and then stop: no pull request, no subscription, and — since this API exposes no full-dataset endpoint either — no route by which you could ever reach the rows you paid for.

That is worse than a knob that quietly does nothing. It is a mode that spends a complete build and silently produces nothing collectable, which is why the request is refused instead of accepted.

publication.policy: "auto" is refused on the same grounds. Accepting it would mean quietly behaving as manual, so you would build an integration expecting no human step and meet the gate in production instead.

The status is 501 and not 400 on purpose: your request is correct and names a mode this API documents. The missing capability is ours — publication pre-authorization, a way to approve publishing up front. It does not exist yet.

There is no bulk data download

GET /v1/builds/{id}/sample returns the field schema and sample rows. It is not an export, and there is no other endpoint that is one.

The finished dataset is delivered through the subscription that approving the publish_review gate registers. If your integration needs the full rows, that delivery is the route — not this API.

Last-Event-ID suppresses, it does not replay

The SSE stream cannot resend frames you missed. A resubscribe gets a fresh full-state snapshot, and the header is used only to drop frames you demonstrably already have. Progress ticks that elapsed during the gap are gone; gate raises and activity items survive only because the snapshot re-carries them. See Streaming.

approve is never inferred

A body that omits approve on a schema_review or publish_review answer is a 400 approve_required — never a decline. See Gates. This is the limit most likely to bite a generated client, because many of them serialize an unset boolean as false.

GET /v1/usage returns 501

Balance, spend and in-flight counts are billing state. This API meters nothing and prices nothing, so a number assembled here would be a number nothing reconciles against. The route is documented rather than removed so the answer is "not available yet" instead of "no such endpoint".

There are no webhooks

Nothing calls you back. See Webhooks for what to use instead.

Revocation is not instant

API keys are cached per server process, so revoking a key takes effect within the cache's TTL rather than immediately. Treat that window as the exposure period for a leaked key, and revoke as soon as you suspect one rather than at the end of a rotation window.

Answers are recorded without an author

An API key resolves to an organization, not a person, so gate answers and messages sent through this API land in the build record with no author attached. If you need to know which of your users approved a schema, record it on your side.

Request ceilings