Base URL and versioning

​

Base URL

Every route in the API reference is relative to https://api.citino.ai/v1: listing your projects, for example, is GET https://api.citino.ai/v1/projects. Use HTTPS. The MCP server has its own address on the app’s host, because Claude and ChatGPT sign in there. See MCP overview.

​

The version is in the path

The v1 in the path is the version. It shows in your access logs, in a pasted curl and in a stack trace, which a header version would not. Every response to an authenticated request also carries a Citino-Api-Version header naming it.

​

What can change inside v1

Inside v1, changes only add. You can rely on these staying as they are:

• every route, its method and its path;
• every field in a response, its name, its type and what it means;
• every parameter a route accepts, and the values it accepts;
• every error code.

What may appear without notice, because it breaks nothing written correctly:

• new routes;
• new optional parameters;
• new fields in a response, and new keys inside an object;
• new values where a field lists kinds (a new engine key, say).

So write clients that ignore fields they do not know, and handle an unfamiliar engine or type value without failing.

​

Limits only widen

Every published limit (requests a minute, rows a page, how many days a report may cover) is a floor. Inside v1 a limit can be raised; it is never lowered. A job that fits today keeps fitting, unless your project itself grows: a report’s budget is counted in prompts × engines × days, so adding prompts or engines can shorten the window one request may cover. See Reports.

​

Breaking changes

Anything that removes or renames a field, narrows what a parameter accepts, or changes what a number means is a new version, /v2, served beside /v1. The old routes then carry Deprecation and Sunset headers, and keep answering for at least 180 days before they are removed. Every change is listed on the Changelog.

​

Related