API policy
Versioning, limits and deprecation.
How the Annsa API is versioned, what counts as a breaking change, how many requests each endpoint allows, and the 90 days of notice you get before anything is taken away.
How versions work
A version is a date. Send it as a header and you pin the contract you built against.
Annsa-Version: 2026-08-22
Leave the header off and you get the current version, which is what happens today if you do nothing. Every response tells you which version answered it, in the same header. Send a version we do not recognize and the request is refused with a 400 that lists the ones we support — we would rather tell you the version does not exist than quietly serve you a different one.
There is one version today, 2026-08-22, and it is the one described in openapi.json. Nothing is deprecated.
What we will not change without telling you
Anything that could break working code needs a new version. Anything that only adds does not.
- Removing an endpoint, a field, or an enum value.
- Making an optional request field required.
- Changing the type or meaning of a field you already receive.
- Changing which credential an endpoint accepts.
- Adding a new endpoint.
- Adding a new optional request field.
- Adding a new field to a response.
- Adding a new enum value to a field you send us, not one you read.
So parse responses in a way that tolerates fields you have not seen before. We will add them.
What it costs you in requests
The limits are there to stop abuse, not to meter you. Your plan quota is a separate thing, counted on your account rather than on the connection.
- POST /feedback
- 5000 an hour. One item or a whole CSV batch counts the same.
- POST /surface/submit
- 5000 an hour. Public submissions from your own users.
- POST /transcripts/upload
- 500 an hour. Each call does real work on the transcript.
- POST /mcp, GET /health
- No limit. Neither declares one, so neither reports one.
You should never have to discover a limit by being refused. Every response from a limited endpoint says where you are in the window, so a client can slow down before it is stopped.
- RateLimit
- Where you stand, in one field: limit, remaining, and reset together.
- RateLimit-Limit
- What the window allows.
- RateLimit-Remaining
- What is left of it.
- RateLimit-Reset
- Seconds until the window resets. A delta, not a timestamp.
- Retry-After
- On a 429 only. How long to wait before trying again.
If something is going away
You get at least 90 days, and you hear it from the API itself rather than from an email you might miss.
Every response from a surface we are retiring carries three headers. They keep arriving for the whole notice period, so a client that only calls us occasionally still finds out with time to move.
- Deprecation
- When we announced it. A timestamp, per RFC 9745.
- Sunset
- The date it stops answering. An HTTP date, per RFC 8594.
- Link
- A pointer back to this page, with rel="sunset".
The 90 days are a minimum, not a target. For anything widely used we would expect to give longer, and to write to the people calling it. If you are building something that would be expensive to move, tell us at support@annsa.ai and we will factor you in before we retire anything you depend on.
For agents
The machine-readable version.
- /openapi.json
The full REST surface, with the version this policy applies to.
- /auth.md
Which credential each endpoint accepts, and what does not exist.
- /.well-known/ai-catalog.json
Everything machine-readable Annsa publishes, in one manifest.
Start free when you are ready.
No card needed. Connect one source and see priorities from your own customer feedback.