HIPS API reference
The public wire contract, rendered: the OpenAI-compatible routes for open-weight language models, the HIPS task API for every other model type and for customer-owned models, uploads, jobs, 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) and the presigned PUT of an upload.
Prelaunch
Every route is a preview until the gateway answers it under the conformance suite. No route answers today; no key exists. The reference never shows a value that could be mistaken for a working credential, host or model id.
| Method and path | Purpose | Status at launch |
|---|---|---|
POST /v1/chat/completions | Chat completion, streamed or not. The first route built and the first validated. | preview |
GET /v1/models | The models and deployments the key may name, with the hips extensions. | preview |
GET /v1/models/{id} | One entry of the list, by catalog id, pinned id or dep_ id. | preview |
POST /v1/responses | OpenAI's Responses shape. Answers 404 route_not_available until its matrix rows pass. | after validation |
POST /v1/tasks | A synchronous task: one request, one batch of inputs, one result array. | preview |
POST /v1/jobs | An asynchronous job: the same body as a task, answered 202 with the job object. | preview |
GET /v1/jobs/{id} | The job object with its status, transitions, result, usage and error. | preview |
GET /v1/jobs | The workspace's jobs, newest first, cursor-paginated. | preview |
POST /v1/jobs/{id}/cancel | Cancels a queued, assigned or running job. | preview |
POST /v1/uploads | A presigned PUT for a task or job input. The gateway never receives the bytes. | preview |
GET /v1/uploads/{id} | The upload's status. | preview |
- Method and path
POST /v1/chat/completions- Purpose
- Chat completion, streamed or not. The first route built and the first validated.
- Status at launch
- preview
- Method and path
GET /v1/models- Purpose
- The models and deployments the key may name, with the
hipsextensions. - Status at launch
- preview
- Method and path
GET /v1/models/{id}- Purpose
- One entry of the list, by catalog id, pinned id or
dep_id. - Status at launch
- preview
- Method and path
POST /v1/responses- Purpose
- OpenAI's Responses shape. Answers 404
route_not_availableuntil its matrix rows pass. - Status at launch
- after validation
- Method and path
POST /v1/tasks- Purpose
- A synchronous task: one request, one batch of inputs, one result array.
- Status at launch
- preview
- Method and path
POST /v1/jobs- Purpose
- An asynchronous job: the same body as a task, answered 202 with the job object.
- Status at launch
- preview
- Method and path
GET /v1/jobs/{id}- Purpose
- The job object with its status, transitions, result, usage and error.
- Status at launch
- preview
- Method and path
GET /v1/jobs- Purpose
- The workspace's jobs, newest first, cursor-paginated.
- Status at launch
- preview
- Method and path
POST /v1/jobs/{id}/cancel- Purpose
- Cancels a queued, assigned or running job.
- Status at launch
- preview
- Method and path
POST /v1/uploads- Purpose
- A presigned PUT for a task or job input. The gateway never receives the bytes.
- Status at launch
- preview
- Method and path
GET /v1/uploads/{id}- Purpose
- The upload's status.
- Status at launch
- preview
Any other OpenAI route (/v1/embeddings, /v1/images/*, /v1/audio/*, /v1/files, /v1/batches, /v1/fine_tuning/*, /v1/assistants, realtime) is not served and answers 404 route_not_found; the task API carries those model types. OpenAI-shaped embeddings and transcriptions after validation are open Not decided yet.
| 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, published only after validation |
| Models | GET /v1/models, GET /v1/models/{id} and the hips entry |
| Tasks | POST /v1/tasks: the envelope, batching, per-input errors |
| Jobs | POST /v1/jobs, GET /v1/jobs/{id}, cancellation, result retrieval, states |
| Uploads | POST /v1/uploads: the presigned PUT, purposes, statuses |
| Deployments | The read side; dep_ ids in model and in deployment |
| Requirements and headers | The four requirements, the hips body object, every x-hips-* and x-ratelimit-* 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, published only after validation
- Page
- Models
- Carries
GET /v1/models,GET /v1/models/{id}and thehipsentry
- Page
- Tasks
- Carries
POST /v1/tasks: the envelope, batching, per-input errors
- Page
- Jobs
- Carries
POST /v1/jobs,GET /v1/jobs/{id}, cancellation, result retrieval, states
- Page
- Uploads
- Carries
POST /v1/uploads: the presigned PUT, purposes, statuses
- Page
- Deployments
- Carries
- The read side;
dep_ids inmodeland indeployment
- Carries
- The four requirements, the
hipsbody object, everyx-hips-*andx-ratelimit-*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
- 11 of 13
- Updated
- 2026-10-21
- Status
- Preview