API Reference
Versioning and compatibility
The Clipia API evolves within one version, /v1 — which changes count as compatible, what goes in the changelog, deprecated fields and SDK versions.
The public API lives at /v1/*, and that is the only current version. We evolve the contract without changing the number and record notable changes in the changelog. The versioning policy is still being refined: there are no notice periods for changes and no separate path version yet.
What we consider compatible
These changes ship without notice and do not change the path version. A client must tolerate them without code changes:
- new endpoints and new optional request parameters;
- new fields in responses, in the
output,warningsanderrorobjects; - new
warnings[].codevalues and new errorcodevalues within existing HTTP statuses; - new models in the catalog and new
inputparameters on models, described in the model'sinput_schema; - changes to
messagetext, which is meant for humans.
Two rules for an integration follow: ignore unknown fields, and branch on code and status, never on the message text. Clients that wait for a terminal status depend on the complete list of status values, so we treat a new value as a breaking change, along with a new error type.
Breaking changes
Removing or renaming an endpoint, field or parameter, changing a field's type or meaning, removing a status value or an error code, or changing the authentication scheme counts as breaking. We call out such a change in the changelog.
Deprecated fields
A field is marked deprecated when it no longer carries meaning but stays in responses for compatibility. Removing a deprecated field is a breaking change.
| Field | Where | Now | Use instead |
|---|---|---|---|
queue_position | responses of submit and status | always 0: the queue position is not computed | status and progress |
SDK versions
The official clients, TypeScript clipia-ai on npm and Python clipia on PyPI, follow semver and are released with the same number: a new field, option or method is a minor release, a fix is a patch, a removal or a type change is a major release. The history lives in the package changelogs and in the portal changelog. The MCP server version is tracked separately and is visible in its metadata.
Service status
The public API has no separate status page and no service level agreement (SLA) today. For questions about outages, contact support: support@clipia.ai and Telegram @clipia_support. If a request returns 503 service_unavailable or 500 internal_error, retry it with a growing pause following the Errors page; credits for a generation that did not start are not charged.
Managing keys
How to create and revoke an API key in the Developer Console, what a new key comes with, where to find its webhook secret, and how many keys you can hold.
Clipia AI Gateway
One OpenAI-compatible API for Claude, GPT, Gemini, DeepSeek and Grok, paid with Clipia credits. Get a key and send your first request in a couple of minutes.