1StopTek
← Back to the developer docs

1st AI Platform API reference

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

Access is limited to invited testers. The planned staging host is not online yet, and no model is connected: inference requests return 503 inference_unavailable. Nothing is charged.

Contract: API v1 · Source: 0b847d90d132

Data plane

Authenticated with a project API key.

GET/api/v1/openapi.json

This OpenAPI document

Request body

No request body.

Responses

  • 200 OpenAPI 3.1 document

GET/api/v1/models

List the models this key may use

Scope `models:read`. Only models that are policy-eligible for the organization and currently servable are listed.

Request body

No request body.

Responses

  • 200 OK
  • 401 Missing or invalid credential (`authentication_error`)
  • 403 Not allowed / insufficient scope (`permission_error`)
  • 429 Rate limited (`rate_limit_error`); see `Retry-After`

GET/api/v1/models/{model_id}

Get one model

Parameters

FieldTypeDescription
model_id (path) · requiredstringModel id

Request body

No request body.

Responses

  • 200 OK
  • 401 Missing or invalid credential (`authentication_error`)
  • 403 Not allowed / insufficient scope (`permission_error`)
  • 404 Not found (`not_found_error`)

POST/api/v1/chat/completions

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.

Request body

FieldTypeDescription
modelstringA 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 · requiredobject[]
max_tokensintegerCapped at the model's and the tier's output limit
max_completion_tokensintegerAlias of max_tokens
temperaturenumber
streamboolean
response_formatobjectStructured output on models with `structured_output`. Not combinable with stream in v1.
userstringAccepted for compatibility; NOT stored

Responses

  • 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 large
  • 422 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`)
Examples · chat
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
  }'
Examples · stream
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]
Examples · structured
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"]
        }
      }
    }
  }'

POST/api/v1/embeddings

Create embeddings

Scope `embeddings:write`. L2-normalized float vectors.

Request body

FieldTypeDescription
modelstring
input · requiredstring | string[]
encoding_formatany

Responses

  • 200 OK
  • 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 large
  • 429 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`
Examples · embeddings
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"]}'

GET/api/v1/usage

Usage of this key's project

Scope `usage:read`.

Parameters

FieldTypeDescription
from (query)stringStart date YYYY-MM-DD (default: first of the month)
to (query)stringEnd date YYYY-MM-DD (default: today, UTC)

Request body

No request body.

Responses

  • 200 OK
  • 400 Invalid request (`invalid_request_error`)
  • 401 Missing or invalid credential (`authentication_error`)
  • 403 Not allowed / insufficient scope (`permission_error`)
Examples · usage
curl -sS "$FIRSTAI_BASE_URL/api/v1/usage" \
  -H "Authorization: Bearer $FIRSTAI_API_KEY"