# Pokee API reference

> Production API reference for Pokee, a US-based inference provider. For a browsable guide, see [API documentation](https://console.pokee.ai/docs).

This reference always uses production URLs, including when read from the development console.

## Quickstart

Create a production API key at [API keys](https://console.pokee.ai/keys) and set the `POKEE_API_KEY` environment variable in your server or terminal. Base URL: `https://api.pokee.ai/v1`.

```bash
curl -N https://api.pokee.ai/v1/chat/completions \
  -H "Authorization: Bearer $POKEE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"model":"pokee-isaac","messages":[{"role":"user","content":"Hello!"}],"max_tokens":256,"stream":true,"stream_options":{"include_usage":true}}'
```

For a synchronous JSON response, set `stream` to `false` and omit `stream_options`. Read generated text from `choices[].message.content`, tool calls from `choices[].message.tool_calls`, and token counts from `usage`.

## Authentication

Send `Authorization: Bearer <POKEE_API_KEY>` on inference and model-list requests. Send `Content-Type: application/json` on JSON requests. Keep API keys server-side; never embed them in a browser bundle. Documentation itself is public and requires no API key.

## Models

Supported model IDs are `pokee-isaac` and `pokee-glm-5.3-flash`. `pokee-isaac` is the default. Both models are listed by `GET /v1/models`; set `model` to select either one. The API returns final content and tool calls; private reasoning deltas are not exposed. Use the exact model ID in requests.

| Model ID | Input context | Output default / maximum | Input USD / 1M tokens | Output USD / 1M tokens |
| --- | --- | --- | --- | --- |
| `pokee-isaac` | Up to approximately 10M tokens | 60,000 / 60,000 | $0.15 | $1.00 |
| `pokee-glm-5.3-flash` | Up to 10M tokens with compression; native input plus output window is 262,144 tokens | 60,000 / 60,000, subject to remaining native context | $0.055 | $0.20 |

The JSON body-size limit also applies. Compressed input capacity and native model context are different constraints.

## Endpoints

Paths are relative to `https://api.pokee.ai/v1`. All endpoints in this table require bearer authentication.

| Method | Path | Purpose |
| --- | --- | --- |
| POST | `/chat/completions` | Synchronous, streaming, or background generation |
| GET | `/models` | Canonical model catalog in OpenRouter schema format |
| GET | `/chat/completions/{id}` | Poll a background completion |
| GET | `/chat/completions/{id}?stream=true&starting_after={sequence}` | Resume a background stream |
| POST | `/chat/completions/{id}/cancel` | Cancel a background completion |

## Chat completions

| Field | Required | Behavior |
| --- | --- | --- |
| `messages` | Yes | Array of OpenAI-compatible chat messages with `role` and `content` |
| `model` | No | Exact supported model ID; defaults to `pokee-isaac` on the standard endpoint |
| `stream` | No | `true` returns SSE; otherwise returns a JSON response |
| `stream_options.include_usage` | No | Set to `true` to request final streaming token usage |
| `max_tokens` / `max_completion_tokens` | No | Positive integer, default and maximum 60,000; if both are supplied their values must agree |
| `tools` | No | OpenAI-compatible function definitions; the caller executes tools |
| `tool_choice` | No | For example, `auto` or a specific function selection |
| `background` | No | Pokee extension for polling, replay, and cancellation |

Both models accept text input and return text and function tool calls. The returned `finish_reason` distinguishes a normal stop, an output limit, and a tool call. Private reasoning deltas are not exposed.

For function calling, supply `tools` with entries shaped as `{"type":"function","function":{"name":"lookup","description":"Look up a value","parameters":{"type":"object","properties":{"query":{"type":"string"}},"required":["query"]}}}`. When the assistant returns `tool_calls`, parse each function's JSON `arguments`, execute it in your application, append the assistant message and a `role: "tool"` message with the matching `tool_call_id`, then request the next completion.

## Streaming

For streaming, parse Server-Sent Events (SSE), accumulate `choices[].delta`, and handle tool-call deltas as well as text. A successful stream ends with a usage event and `data: [DONE]`. Usage-only events may have an empty `choices` array. GLM usage exposes aggregate `prompt_tokens`, `completion_tokens`, and `total_tokens`; provider-specific usage detail objects are omitted. Ignore SSE comments and handle error events even after HTTP 200; a disconnected stream is not evidence of successful completion.

Example using the Python `openai` package (`pip install openai`):

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["POKEE_API_KEY"],
    base_url="https://api.pokee.ai/v1",
    timeout=600.0,
)
stream = client.chat.completions.create(
    model="pokee-isaac",
    messages=[{"role": "user", "content": "Say hello in one sentence."}],
    max_tokens=256,
    stream=True,
    stream_options={"include_usage": True},
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
    if chunk.usage:
        print("\nUsage:", chunk.usage)
```

A normal streamed request ends if the caller disconnects. Use background mode when the result must remain available after a disconnect.

## Long context

Pokee Isaac has a documented input context of up to approximately 10 million tokens. GLM Flash has a native 262,144-token input-plus-output window; Pokee's context-compression serving layer advertises up to 10 million input tokens. These are distinct limits: long inputs are compressed before GLM inference. Both models are subject to the encoded JSON request-body limit of 45 MiB (47,185,920 bytes). The gateway output default and maximum are 60,000 tokens; the inference service may reduce the output allowance to fit the remaining model context. Set `max_tokens` or `max_completion_tokens` to bound output; if both are supplied they must agree. Requests larger than 16 MiB require `stream: true` and `Accept: text/event-stream`, and do not support background mode or idempotency. Token counts and byte limits are different constraints; the byte limit does not guarantee that every 10-million-token prompt will fit. Allow at least 10 minutes of client timeout for multi-million-token inputs.

To select GLM, change the JSON `model` to `pokee-glm-5.3-flash`. For a GLM request body larger than 16 MiB, also send `X-Pokee-Model: pokee-glm-5.3-flash`; this header selects the model before the large body is streamed upstream and must match the JSON model.

Large uploads must include their `Content-Length`. With curl, put the complete JSON body (including `stream: true`) in a file and use `--data-binary @request.json`. The byte limit applies to the complete encoded JSON body, not just message text. Latency depends on input size and load; no fixed response time is guaranteed.

## Background

Pokee also offers background Chat Completions with polling, stream replay, and cancellation. The current generation time limit is 20 minutes; completed, failed, or cancelled background resources are retained for approximately 10 minutes before expiry. This is a Pokee extension to Chat Completions; it is not an OpenAI Responses API endpoint.

Create a replayable background completion:

```bash
curl https://api.pokee.ai/v1/chat/completions \
  -H "Authorization: Bearer $POKEE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-report-id" \
  -d '{"model":"pokee-isaac","messages":[{"role":"user","content":"Write a report."}],"max_tokens":1024,"background":true,"stream":true}'
```

Save the returned resource `id`. Poll with `GET /chat/completions/{id}`. States are `in_progress`, `completed`, `failed`, and `cancelled`. To resume, use `GET /chat/completions/{id}?stream=true&starting_after=42`, where 42 is the last received sequence number, or send `Last-Event-ID`. The query parameter takes precedence. Background chunks include `sequence_number` and matching SSE `id` values. Only resources created with `stream: true` support stream replay; otherwise resume returns `400 not_streamable`. Polling works for both modes. Cancel with `POST /chat/completions/{id}/cancel`; repeated cancellation returns the current resource.

## Idempotency

Use a unique `Idempotency-Key` for each logical operation when retrying must not start another generation or charge. The key must be printable and at most 200 characters. Reusing it with a different body returns `422 idempotency_key_reused`. A duplicate synchronous request that cannot replay its response returns `409 idempotency_key_replayed`. A duplicate background request can return the original resource while it remains available. Bodies over 16 MiB do not support idempotency or background mode.

## Rate limits

Default limits per customer account are 500 requests per minute, 20 million input-plus-output tokens per minute, and 10 concurrent requests on free accounts or 25 on paid accounts. Keys and models belonging to the same account share its limits. Minute limits use fixed one-minute windows, with tokens counted when usage settles. Paid concurrency applies to accounts that have purchased credits. Customer-specific overrides and shared service-capacity limits may apply. On HTTP 429, respect `Retry-After` and the returned rate-limit headers; use bounded retries with backoff.

## Errors

Errors use an OpenAI-compatible JSON envelope, for example:

```json
{"error":{"message":"Missing API key","type":"authentication_error","code":"invalid_api_key"}}
```

| HTTP status | Code or type | Action |
| --- | --- | --- |
| 400 | `invalid_request_error`, `model_not_found`, `invalid_max_tokens`, `model_mismatch` | Correct the request, supported model ID, matching model selection, or output limit |
| 400 | `large_request_requires_sse` | Follow the large-upload streaming requirements |
| 401 | `invalid_api_key` | Supply a valid bearer key |
| 402 | `insufficient_credits` | Add credits or reduce the request's reservation |
| 403 | `key_revoked` | Create a replacement key |
| 404 | `response_not_found` | Check the resource ID and account; expired resources cannot be retrieved |
| 409 | `idempotency_key_replayed` | Do not submit the same completed synchronous operation again |
| 413 | `payload_too_large` | Reduce encoded JSON body size |
| 422 | `idempotency_key_reused` | Use the same body or a new logical-operation key |
| 429 | `rate_limit_exceeded` | Wait for `Retry-After`, then retry with bounded backoff |
| 502 | `upstream_error` | Inspect the error and retry transient failures cautiously |
| 503 | `service_unavailable` | Retry with bounded backoff |

For 400 responses, `type` is generally `invalid_request_error`; `code` narrows the cause. Streaming errors can occur after HTTP 200, so check SSE events as well as the initial status. A disconnected or incomplete stream is not a successful completion.

## Pricing

Rates are listed in the model table above in USD per one million tokens. Console billing uses credits: 1 credit equals USD $0.01. Positive request charges round up to whole credits, with a minimum charge of 1 credit. Available credits equal settled balance minus active reservations. A request requires enough available credits for its estimated input and output reservation. Failed or interrupted generations accepted by the inference service may be billed using estimated usage if final usage is unavailable. Per-request usage and charges are available in the [console usage page](https://console.pokee.ai/usage).

## Data and privacy

Pokee does not persist inference prompts in its own application storage. Operational inference logs contain approximately 120-character truncated previews of each message and are retained for one day by the infrastructure provider. Separately, the infrastructure provider retains raw request payloads encrypted at rest for up to seven days for operational purposes. No prompt data is used for training under the published policy.

Account usage records contain request metadata such as token counts, timestamps, model, credits, API key ID, and caller IP, rather than prompt bodies. Background response content is stored temporarily for polling and replay and deleted approximately ten minutes after completion. This service does not promise zero data retention.

See the [Privacy Policy](https://pokee.ai/legal/privacy-policy) and [Terms of Service](https://pokee.ai/legal/terms-of-service).

## Provider integration

`GET https://api.pokee.ai/v1/models` is the canonical model catalog. It returns `{"data": [...]}` with each entry conforming directly to OpenRouter's model schema; entries do not include OpenAI-specific `object` or `owned_by` fields. `GET /v1/openrouter/models` is a compatibility alias returning the identical response. It uses the same bearer authentication as inference and returns OpenRouter schema version `2.4` metadata: model IDs, text input/output capabilities, streaming, tool calling, context/output limits, and decimal USD-per-token prices. Read `is_ready` for a model's OpenRouter routing readiness; a model's presence in the feed does not mean it is available through OpenRouter.

Configure a separate OpenAI-compatible base URL for each model: `https://api.pokee.ai/v1/openrouter/pokee-isaac` or `https://api.pokee.ai/v1/openrouter/pokee-glm-5.3-flash`. Each exposes `GET /models` for that model and `POST /chat/completions`. Use the same production bearer key. The URL selects the model even when the JSON model is omitted; an explicitly supplied model or `X-Pokee-Model` must agree with the URL. The same account limits and credit requirements apply.

For requests larger than 16 MiB on a model-specific provider URL, send a known Content-Length and `stream: true`; the URL selects the upstream before upload, so neither a custom model header nor an explicit SSE Accept header is required. The response is SSE. The body-size limit, matching-model validation, and restrictions on background mode and idempotency still apply. The ordinary `/chat/completions` endpoint retains its existing custom-header requirements for large GLM requests.

Contact [support@pokee.ai](mailto:support@pokee.ai) for provider integration questions.