GET/api/v1/openapi.json
This OpenAPI document
Request body
No request body.
Responses
200OpenAPI 3.1 document
Generated from the API contract (OpenAPI 3.1) that the server is tested against. Developer access is in testing: endpoints are implemented but not publicly available yet.
Restricted testing
Contract: API v1 · Source: 0b847d90d132
Data plane
This OpenAPI document
No request body.
200 OpenAPI 3.1 documentList the models this key may use
Scope `models:read`. Only models that are policy-eligible for the organization and currently servable are listed.
No request body.
200 OK401 Missing or invalid credential (`authentication_error`)403 Not allowed / insufficient scope (`permission_error`)429 Rate limited (`rate_limit_error`); see `Retry-After`Get one model
| Field | Type | Description |
|---|---|---|
model_id (path) · required | string | Model id |
No request body.
200 OK401 Missing or invalid credential (`authentication_error`)403 Not allowed / insufficient scope (`permission_error`)404 Not found (`not_found_error`)Create a chat completion
Scope `chat:write`. With `stream: true` the response is `text/event-stream`: `data: <ChatCompletionChunk>` events, ending with `data: [DONE]`. A failure after the stream started is sent as `data: {"error": {...}}` before `[DONE]`. Everything that can be refused (validation, safety, limits, model selection) is refused with an HTTP status BEFORE the stream starts.
| Field | Type | Description |
|---|---|---|
model | string | A model id from /api/v1/models; omit or `auto` for the environment's default model; if it is unavailable, the request may fail over only to a deployment declared equivalent to it. An explicit model is never substituted. |
messages · required | object[] | |
max_tokens | integer | Capped at the model's and the tier's output limit |
max_completion_tokens | integer | Alias of max_tokens |
temperature | number | |
stream | boolean | |
response_format | object | Structured output on models with `structured_output`. Not combinable with stream in v1. |
user | string | Accepted for compatibility; NOT stored |
200 Completion (or event stream when `stream: true`)400 Invalid request (`invalid_request_error`)401 Missing or invalid credential (`authentication_error`)402 Monthly token allowance used up (`quota_exceeded_error`, code `monthly_quota_exceeded`) or the organization's spending limit would be exceeded (code `spending_limit_reached`; `currency`, `hard_limit_micros`, exact `month_to_date_cost_pico`, `held_cost_pico` (open reservations), `request_worst_case_pico`, and their rounded `*_micros` display values)403 Not allowed / insufficient scope (`permission_error`)404 Not found (`not_found_error`)413 Input too large422 Refused by the Safety Layer before any model call (`safety_error`, code `safety_refused`)429 Rate limited (`rate_limit_error`); see `Retry-After`500 Internal error (`api_error`)502 Model failure or invalid structured output (`model_error`)503 No model available (`service_unavailable_error`); retry; or usage/spend limits cannot be checked (code `billing_unavailable`, `service_unavailable_error`; fail closed, nothing was run); retry after `Retry-After`504 Model timeout (`model_error`)curl -sS "$FIRSTAI_BASE_URL/api/v1/chat/completions" \
-H "Authorization: Bearer $FIRSTAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"messages": [
{"role": "system", "content": "You answer in one sentence."},
{"role": "user", "content": "What is an API key?"}
],
"max_tokens": 120
}'curl -sS -N "$FIRSTAI_BASE_URL/api/v1/chat/completions" \
-H "Authorization: Bearer $FIRSTAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"messages": [{"role": "user", "content": "Count from one to five."}],
"max_tokens": 60,
"stream": true
}'
# data: {"object":"chat.completion.chunk","choices":[{"delta":{"content":"One"},...}]}
# ...
# data: [DONE]curl -sS "$FIRSTAI_BASE_URL/api/v1/chat/completions" \
-H "Authorization: Bearer $FIRSTAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"messages": [{"role": "user", "content": "Extract: Berlin is the capital of Germany."}],
"max_tokens": 120,
"response_format": {
"type": "json_schema",
"json_schema": {
"name": "fact",
"schema": {
"type": "object",
"properties": {"city": {"type": "string"}, "country": {"type": "string"}},
"required": ["city", "country"]
}
}
}
}'Create embeddings
Scope `embeddings:write`. L2-normalized float vectors.
| Field | Type | Description |
|---|---|---|
model | string | |
input · required | string | string[] | |
encoding_format | any |
200 OK400 Invalid request (`invalid_request_error`)401 Missing or invalid credential (`authentication_error`)402 Monthly token allowance used up (`quota_exceeded_error`, code `monthly_quota_exceeded`) or the organization's spending limit would be exceeded (code `spending_limit_reached`; `currency`, `hard_limit_micros`, exact `month_to_date_cost_pico`, `held_cost_pico` (open reservations), `request_worst_case_pico`, and their rounded `*_micros` display values)403 Not allowed / insufficient scope (`permission_error`)404 Not found (`not_found_error`)413 Input too large429 Rate limited (`rate_limit_error`); see `Retry-After`503 Embeddings unavailable; or usage/spend limits cannot be checked (code `billing_unavailable`, `service_unavailable_error`; fail closed, nothing was run); retry after `Retry-After`curl -sS "$FIRSTAI_BASE_URL/api/v1/embeddings" \
-H "Authorization: Bearer $FIRSTAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"input": ["first document", "second document"]}'Usage of this key's project
Scope `usage:read`.
| Field | Type | Description |
|---|---|---|
from (query) | string | Start date YYYY-MM-DD (default: first of the month) |
to (query) | string | End date YYYY-MM-DD (default: today, UTC) |
No request body.
200 OK400 Invalid request (`invalid_request_error`)401 Missing or invalid credential (`authentication_error`)403 Not allowed / insufficient scope (`permission_error`)curl -sS "$FIRSTAI_BASE_URL/api/v1/usage" \
-H "Authorization: Bearer $FIRSTAI_API_KEY"