HIPS API reference
The public wire contract, rendered: the OpenAI-compatible routes for open-weight language models, Anthropic's Messages API, embeddings and rerank, OpenAI's image routes, the HIPS task API for every other model type, the request requirements, the response headers, the error envelope, usage and versioning. Every route is relative to the base URL https://ai.hips.com/v1, the value of HIPS_BASE_URL; HTTPS only; JSON bodies with Content-Type: application/json, except streaming responses (text/event-stream).
Note
The routes marked served answer in production today, with an API key created in the Console. A route's state in production is not its validation: every row of the compatibility matrix stays unvalidated until it passes the conformance suite. The reference never shows a value that could be mistaken for a working credential, host or model id.
| Method and path | Purpose | In production |
|---|---|---|
POST /v1/chat/completions | Chat completion in OpenAI's shape, streamed or not. | served |
POST /v1/responses | OpenAI's Responses shape, stateless: HIPS stores no response, so every request carries its whole conversation. | served |
POST /v1/messages | Anthropic's Messages API, with x-api-key and anthropic-version: 2023-06-01, in Anthropic's error shape. | served |
POST /v1/messages/count_tokens | Answers 404 route_not_available in Anthropic's shape: each answer's usage carries the exact counts. | not served |
GET /v1/models | The routers, models and deployments the key may name, with the hips extensions. | served |
GET /v1/models/{id} | One entry of the list, by catalog id, pinned id, router name or dep_ id. | served |
GET /v1/feeds/certified/models | The Certified pool's price feed: one document per model under <model id>:certified, with no key. | served |
GET /v1/feeds/community/models | The Community pool's price feed: one document per model under <model id>:community, with no key. | served |
GET /v1/feeds/models | Both pools' price feeds in one: the Community offer as service_tier: "flex" under the Certified offer's id, with no key. | served |
POST /v1/embeddings | Embeddings in OpenAI's shape, billed per started second of compute. A model answers once an embedding model is published and priced. | served |
POST /v1/rerank | Rerank in Cohere's shape, billed per started second of compute. A model answers once a reranker is published and priced. | served |
POST /v1/tasks | A synchronous task: one request, one batch of inputs, one result array. | served |
POST /v1/audio/transcriptions | Answers 400 type_not_served: no speech-to-text model is served yet. Opens once the type is served. | not served |
POST /v1/audio/speech | Answers 400 type_not_served: no text-to-speech model is served yet. Opens once the type is served. | not served |
POST /v1/images/generations | Image generation in OpenAI's JSON shape, billed per image at its size. Answers 400 type_not_served while no image generation model is served. | served |
POST /v1/images/edits | Image editing in OpenAI's multipart shape, billed per image at its size. Answers 400 type_not_served while no image editing model is served. | served |
POST /v1/uploads | A presigned PUT for a task input. Not offered in production yet: 404 route_not_available. | not offered |
GET /v1/uploads/{id} | The upload's status. Not offered in production yet: 404 route_not_available. | not offered |
DELETE /v1/uploads/{id} | Deletes the upload and its bytes. Not offered in production yet: 404 route_not_available. | not offered |
POST /v1/files | OpenAI's Files API for batch input files. Not offered in production yet: 404 route_not_available. | not offered |
GET /v1/files | The files the credential reaches, OpenAI's list. Not offered in production yet. | not offered |
GET /v1/files/{file_id} | The File object. Not offered in production yet. | not offered |
GET /v1/files/{file_id}/content | The file's bytes, streamed. Not offered in production yet. | not offered |
DELETE /v1/files/{file_id} | Deletes the file from storage at once. Not offered in production yet. | not offered |
POST /v1/batches | OpenAI's Batch API. Not offered in production yet: 404 route_not_available. | not offered |
GET /v1/batches | The batches the credential reaches, newest first. Not offered in production yet. | not offered |
GET /v1/batches/{batch_id} | The Batch object. Not offered in production yet. | not offered |
POST /v1/batches/{batch_id}/cancel | Cancels a batch. Not offered in production yet. | not offered |
POST /v1/jobs | The asynchronous job route is not built: 404 route_not_found. | not built |
GET /v1/jobs/{id} | Not built: 404 route_not_found. | not built |
GET /v1/jobs | Not built: 404 route_not_found. | not built |
POST /v1/jobs/{id}/cancel | Not built: 404 route_not_found. | not built |
- Method and path
POST /v1/chat/completions- Purpose
- Chat completion in OpenAI's shape, streamed or not.
- In production
- served
- Method and path
POST /v1/responses- Purpose
- OpenAI's Responses shape, stateless: HIPS stores no response, so every request carries its whole conversation.
- In production
- served
- Method and path
POST /v1/messages- Purpose
- Anthropic's Messages API, with
x-api-keyandanthropic-version: 2023-06-01, in Anthropic's error shape. - In production
- served
- Method and path
POST /v1/messages/count_tokens- Purpose
- Answers 404
route_not_availablein Anthropic's shape: each answer'susagecarries the exact counts. - In production
- not served
- Method and path
GET /v1/models- Purpose
- The routers, models and deployments the key may name, with the
hipsextensions. - In production
- served
- Method and path
GET /v1/models/{id}- Purpose
- One entry of the list, by catalog id, pinned id, router name or
dep_id. - In production
- served
- Method and path
GET /v1/feeds/certified/models- Purpose
- The Certified pool's price feed: one document per model under
<model id>:certified, with no key. - In production
- served
- Method and path
GET /v1/feeds/community/models- Purpose
- The Community pool's price feed: one document per model under
<model id>:community, with no key. - In production
- served
- Method and path
GET /v1/feeds/models- Purpose
- Both pools' price feeds in one: the Community offer as
service_tier: "flex"under the Certified offer's id, with no key. - In production
- served
- Method and path
POST /v1/embeddings- Purpose
- Embeddings in OpenAI's shape, billed per started second of compute. A model answers once an embedding model is published and priced.
- In production
- served
- Method and path
POST /v1/rerank- Purpose
- Rerank in Cohere's shape, billed per started second of compute. A model answers once a reranker is published and priced.
- In production
- served
- Method and path
POST /v1/tasks- Purpose
- A synchronous task: one request, one batch of inputs, one result array.
- In production
- served
- Method and path
POST /v1/audio/transcriptions- Purpose
- Answers 400
type_not_served: no speech-to-text model is served yet. Opens once the type is served. - In production
- not served
- Method and path
POST /v1/audio/speech- Purpose
- Answers 400
type_not_served: no text-to-speech model is served yet. Opens once the type is served. - In production
- not served
- Method and path
POST /v1/images/generations- Purpose
- Image generation in OpenAI's JSON shape, billed per image at its size. Answers 400
type_not_servedwhile no image generation model is served. - In production
- served
- Method and path
POST /v1/images/edits- Purpose
- Image editing in OpenAI's multipart shape, billed per image at its size. Answers 400
type_not_servedwhile no image editing model is served. - In production
- served
- Method and path
POST /v1/uploads- Purpose
- A presigned PUT for a task input. Not offered in production yet: 404
route_not_available. - In production
- not offered
- Method and path
GET /v1/uploads/{id}- Purpose
- The upload's status. Not offered in production yet: 404
route_not_available. - In production
- not offered
- Method and path
DELETE /v1/uploads/{id}- Purpose
- Deletes the upload and its bytes. Not offered in production yet: 404
route_not_available. - In production
- not offered
- Method and path
POST /v1/files- Purpose
- OpenAI's Files API for batch input files. Not offered in production yet: 404
route_not_available. - In production
- not offered
- Method and path
GET /v1/files- Purpose
- The files the credential reaches, OpenAI's list. Not offered in production yet.
- In production
- not offered
- Method and path
GET /v1/files/{file_id}- Purpose
- The File object. Not offered in production yet.
- In production
- not offered
- Method and path
GET /v1/files/{file_id}/content- Purpose
- The file's bytes, streamed. Not offered in production yet.
- In production
- not offered
- Method and path
DELETE /v1/files/{file_id}- Purpose
- Deletes the file from storage at once. Not offered in production yet.
- In production
- not offered
- Method and path
POST /v1/batches- Purpose
- OpenAI's Batch API. Not offered in production yet: 404
route_not_available. - In production
- not offered
- Method and path
GET /v1/batches- Purpose
- The batches the credential reaches, newest first. Not offered in production yet.
- In production
- not offered
- Method and path
GET /v1/batches/{batch_id}- Purpose
- The Batch object. Not offered in production yet.
- In production
- not offered
- Method and path
POST /v1/batches/{batch_id}/cancel- Purpose
- Cancels a batch. Not offered in production yet.
- In production
- not offered
- Method and path
POST /v1/jobs- Purpose
- The asynchronous job route is not built: 404
route_not_found. - In production
- not built
- Method and path
GET /v1/jobs/{id}- Purpose
- Not built: 404
route_not_found. - In production
- not built
- Method and path
GET /v1/jobs- Purpose
- Not built: 404
route_not_found. - In production
- not built
- Method and path
POST /v1/jobs/{id}/cancel- Purpose
- Not built: 404
route_not_found. - In production
- not built
| State | What a caller gets |
|---|---|
served | The route answers in production. |
not offered | Built and not switched on in production: 404 route_not_available (uploads, files, batches). |
not served | The route answers a refusal until its type is served or its build lands: 400 type_not_served, or 404 route_not_available. |
not built | No route exists: 404 route_not_found. |
- State
served- What a caller gets
- The route answers in production.
- State
not offered- What a caller gets
- Built and not switched on in production: 404
route_not_available(uploads, files, batches).
- State
not served- What a caller gets
- The route answers a refusal until its type is served or its build lands: 400
type_not_served, or 404route_not_available.
- State
not built- What a caller gets
- No route exists: 404
route_not_found.
Every other path, OpenAI's and Anthropic's included (/v1/fine_tuning/*, /v1/assistants, realtime, /v1/messages/batches, a stored response under /v1/responses/), answers 404 route_not_found; a known path with another method answers 404 method_not_allowed with Allow.
| Page | Carries |
|---|---|
| Authentication | API keys and a person's access token, Authorization: Bearer, key kinds, workspace state |
| Chat completions | POST /v1/chat/completions, every field, the model values, streaming, features |
| Responses | POST /v1/responses: the stateless request, the output items, the streamed events |
| Messages | POST /v1/messages: Anthropic's Messages API, its headers, events and error shape |
| Count tokens | POST /v1/messages/count_tokens, not served yet |
| Models | GET /v1/models, GET /v1/models/{id} and the hips entry |
| Prices API | HIPS's published prices by machine, on https://hips.com with no key: the catalog, one model's rates and the price history |
| Tasks | POST /v1/tasks: the envelope, the task types, per-input errors |
| Embeddings and rerank | POST /v1/embeddings in OpenAI's shape and POST /v1/rerank in Cohere's, billed per started second |
| Images | POST /v1/images/generations and POST /v1/images/edits in OpenAI's shapes, billed per image at its size |
| Jobs | The asynchronous job routes, not built yet |
| Uploads | POST /v1/uploads: the presigned PUT, purposes, statuses; not offered in production yet |
| Files | OpenAI's Files API for batch files; not offered in production yet |
| Batches | OpenAI's Batch API and the Batch object; not offered in production yet |
| Webhooks | The batch events, their signatures and the Console's endpoint tools |
| Vector stores | OpenAI's vector store API for Knowledge; not switched on in production yet |
| Deployments | The read side; dep_ ids in model and in deployment |
| Requirements and headers | The four requirements, the hips body object, every request and response header |
| Errors | The envelope and every type and code |
| Usage | Usage fields per billing unit; money separate from units |
| Versioning | How the contract is versioned and deprecated |
- Page
- Authentication
- Carries
- API keys and a person's access token,
Authorization: Bearer, key kinds, workspace state
- Page
- Chat completions
- Carries
POST /v1/chat/completions, every field, themodelvalues, streaming, features
- Page
- Responses
- Carries
POST /v1/responses: the stateless request, the output items, the streamed events
- Page
- Messages
- Carries
POST /v1/messages: Anthropic's Messages API, its headers, events and error shape
- Page
- Count tokens
- Carries
POST /v1/messages/count_tokens, not served yet
- Page
- Models
- Carries
GET /v1/models,GET /v1/models/{id}and thehipsentry
- Page
- Prices API
- Carries
- HIPS's published prices by machine, on
https://hips.comwith no key: the catalog, one model's rates and the price history
- Page
- Tasks
- Carries
POST /v1/tasks: the envelope, the task types, per-input errors
- Carries
POST /v1/embeddingsin OpenAI's shape andPOST /v1/rerankin Cohere's, billed per started second
- Page
- Images
- Carries
POST /v1/images/generationsandPOST /v1/images/editsin OpenAI's shapes, billed per image at its size
- Page
- Jobs
- Carries
- The asynchronous job routes, not built yet
- Page
- Uploads
- Carries
POST /v1/uploads: the presigned PUT, purposes, statuses; not offered in production yet
- Page
- Files
- Carries
- OpenAI's Files API for batch files; not offered in production yet
- Page
- Batches
- Carries
- OpenAI's Batch API and the Batch object; not offered in production yet
- Page
- Webhooks
- Carries
- The batch events, their signatures and the Console's endpoint tools
- Page
- Vector stores
- Carries
- OpenAI's vector store API for Knowledge; not switched on in production yet
- Page
- Deployments
- Carries
- The read side;
dep_ids inmodeland indeployment
- Carries
- The four requirements, the
hipsbody object, every request and response header
- Page
- Errors
- Carries
- The envelope and every type and code
- Page
- Usage
- Carries
- Usage fields per billing unit; money separate from units
- Page
- Versioning
- Carries
- How the contract is versioned and deprecated
Related sheets
- Sheet
- 18 of 20
- Updated
- 2026-11-16