Application API

Documentation / Reference / Application API

Your application talks to Pointsman; Pointsman authenticates its virtual key, applies its controls and calls an eligible model. You supply provider credentials to the gateway, not to every application. This page explains the application-facing HTTP contract with examples you can adapt after the quickstart.

The launch scope is Chat Completions. This is not support for every endpoint or field in another provider's API. Read the compatibility matrix for provider differences and explicit refusals. The examples here are illustrative; this documentation update did not execute live-provider requests.

Base URL and authentication#

For the local quickstart, use http://localhost:8080. Use your deployment's HTTPS address outside that local setup. Every endpoint below uses a Pointsman virtual key:

Authorization: Bearer <your-pointsman-virtual-key>

Set these variables in a private terminal for the curl examples. Replace both placeholders before running; use a model or group your key is permitted to access.

export POINTSMAN_URL='http://localhost:8080'
export POINTSMAN_KEY='<your-pointsman-virtual-key>'
export POINTSMAN_MODEL='<allowed-model-or-group>'

Do not use your provider key or dashboard password as the bearer token. Admin calls use a separate authentication surface described in the admin API. The examples use curl and jq; jq constructs JSON safely from shell variables.

Endpoints at a glance#

Responses, embeddings, audio, batch and rerank APIs are not implemented. Tool pass-through does not execute a tool or authorize the tool's eventual actions.

Create a Chat Completion#

POST /v1/chat/completions accepts Content-Type: application/json.

jq -n --arg model "$POINTSMAN_MODEL" '{
  model: $model,
  messages: [
    {role: "system", content: "Explain technical concepts in plain language."},
    {role: "user", content: "What does an AI gateway do?"}
  ],
  max_tokens: 128,
  temperature: 0,
  stream: false
}' | curl --fail-with-body --silent --show-error \
  --dump-header response-headers.txt \
  "$POINTSMAN_URL/v1/chat/completions" \
  -H "Authorization: Bearer $POINTSMAN_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @-

Requests to a live provider may incur charges. A representative response looks like this; IDs, text, model identifiers and token counts vary:

{
  "id": "chatcmpl-example",
  "object": "chat.completion",
  "created": 1800000000,
  "model": "support-chat",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "An AI gateway manages your application's calls to AI models."},
      "finish_reason": "stop"
    }
  ],
  "usage": {"prompt_tokens": 25, "completion_tokens": 18, "total_tokens": 43}
}

On synchronous provider-served responses, X-Served-Provider and X-Provider-Model help identify what answered. Cache hits and live streams have different header availability; see the header reference. Do not assume an absent header has a default value.

Request fields and boundaries#

The compatibility matrix includes the remaining explicitly refused controls. The adapter matrix explains forwarding differences. Unknown fields are not a general pass-through contract. Context checks use the configured tokenizer mode and model metadata; chat framing and tool scaffolding still limit provider-exact counting claims. In exact-tokenizer mode the count is taken after model resolution, with the encoding of the model or group that will serve, so an unknown model behaves as the key's resolution policy says and an omitted model is resolved by the blank-model path (key default, tenant default, semantic group, mode tier, cheapest allowed), the same as in estimate mode, unless the key or the gateway is set to refuse it (400 model_required).

Request headers#

Use X-Request-ID to supply a correlation ID (1–128 characters from letters, digits, ., _ and -), or let the gateway generate one. Use X-Cache-Control: no-cache when deliberately bypassing both cache tiers, for example while checking provider connectivity. This can increase provider calls and charges.

Other cache, guardrail and routing-related headers are described in the header reference and the feature guides. These headers do not bypass a virtual key's permissions or spending controls.

Stream a completion#

Use the same endpoint with stream: true. curl --no-buffer displays data as it arrives instead of buffering output:

jq -n --arg model "$POINTSMAN_MODEL" '{
  model: $model,
  messages: [{role: "user", content: "Explain a gateway in three short sentences."}],
  max_tokens: 128,
  stream: true
}' | curl --fail-with-body --silent --show-error --no-buffer \
  "$POINTSMAN_URL/v1/chat/completions" \
  -H "Authorization: Bearer $POINTSMAN_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @-

Consume SSE records, not arbitrary TCP chunks. A text event has a chat.completion.chunk object with choices[].delta; append content deltas to build the answer. Handle empty deltas, finish information and usage separately. A normal stream terminates with data: [DONE].

data: {"id":"chatcmpl-example","object":"chat.completion.chunk","created":1800000000,"model":"support-chat","choices":[{"index":0,"delta":{"content":"An AI gateway"},"finish_reason":null}]}

data: [DONE]

This abbreviated illustration omits intervening chunks. Tool calls are emitted as an assembled chunk when complete, not progressive argument fragments. The gateway owns upstream usage requests; sending stream_options does not change that. For a provider configured as a registry row, upstream stream usage is requested only when the operator set the row's streamUsage quirk; otherwise the stream carries no usage chunk.

Check both the initial HTTP status and error payloads arriving after the stream starts. HTTP 200 cannot become a different status after headers have been sent. An interrupted stream may contain partial output and estimated usage. Avoid blindly retrying it as if no provider work occurred.

Discover available models#

curl --fail-with-body --silent --show-error \
  "$POINTSMAN_URL/v1/models" \
  -H "Authorization: Bearer $POINTSMAN_KEY" | jq .

The response is a list object with data entries. A concrete model uses object: "model"; a routing group uses object: "model-group". Entries have id, object, created and owned_by. Optional metadata includes family, tier, cost_per_1k, modality, context, params, tags, aliases, deprecated and alias_for. Omitted metadata means it was not supplied, not that a capability or limit is unlimited. cost_per_1k is configured input pricing metadata; it is not a complete input/output price quote or live provider invoice.

Retrieve a single entry by URL-encoding its identifier:

MODEL_PATH=$(jq -rn --arg id "$POINTSMAN_MODEL" '$id | @uri')
curl --fail-with-body --silent --show-error \
  "$POINTSMAN_URL/v1/models/$MODEL_PATH" \
  -H "Authorization: Bearer $POINTSMAN_KEY"

Discovery is scoped to the caller. A 404 on this endpoint does not distinguish an unknown identifier from one the key cannot access. Listing a model is not proof that the provider is healthy or that every optional request control is supported.

Send outcome feedback#

POST /v1/feedback is for the outcome-learning router. A weighted-random or direct model request does not become trainable just because you send a rating.

For an eligible decision, save X-Decision-Receipt from the completion response and send it as decision_id. Prefer this signed receipt to the bare X-Decision-Id when using multiple gateway instances. Use the same virtual key that made the call.

export POINTSMAN_DECISION='<X-Decision-Receipt-from-the-response>'
jq -n --arg decision "$POINTSMAN_DECISION" '{
  decision_id: $decision,
  rating: 1,
  revision: 0
}' | curl --fail-with-body --silent --show-error \
  "$POINTSMAN_URL/v1/feedback" \
  -H "Authorization: Bearer $POINTSMAN_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @-

A rating revises the decision it names; it does not count as an extra observation.

A valid submission normally returns 202 {"accepted":true}. This acknowledges submission, not proof that a policy changed. Unknown, expired or ineligible provenance can be ignored without revealing whether someone else's decision exists. A disabled feedback service can return 503; feedback rate limits can return 429 with Retry-After. Use your actual task result as feedback, such as whether an extraction passed validation. How learning uses feedback.

Errors and retries#

Most gateway errors use an error object with message and type; code and param are included where provided. Parse defensively rather than requiring every field. For example, an unsupported control can identify both the field and the unsupported_request_control code.

These categories are not an exhaustive error-code catalogue. Use bounded retries with backoff for transient failures, and consider whether the upstream may already have processed the request. This page does not promise exactly-once completion or idempotent billing for a retried chat request.

When reporting an issue, include a redacted request shape, gateway version, request ID, status/error code and whether it streamed or hit cache. Exclude credentials and sensitive prompt content. Request investigation.

Implementation references#

The contract above was checked against the current chat request, chat response, model entry, feedback request and the controllers. Runtime/provider verification remains part of release qualification.