Run a prompt

POST/v1/prompts/{slug}/completions

Run a prompt.

Renders a version of the prompt with the given variables and sends it to the model as a chat completion, with the version's model (or model_override), temperature, max_tokens, top_p and stop. The answer is a chat completion, as from POST /v1/chat/completions; with stream: true it is a stream of server-sent events, each a chat.completion.chunk, ending with data: [DONE]. The request is logged and billed like any chat completion on the key, and attributed to the prompt and version for its analytics.

Authenticate with a virtual key (Authorization: Bearer <api_key> or x-virtual-key); the prompt is looked up in the key's organization. A key bound to a workspace runs that workspace's prompts and the organization-level ones; another workspace's prompt is a 404. The response cache, guardrails and routing configs apply through their headers; the x-retry-* and x-fallback-* headers are not read. Response headers: x-cache-status, x-retry-count, x-virtual-key-slug, x-fallback-provider when a fallback answered, and x-guardrail-status when a guardrail applied.

Errors: 400 for an invalid version_ref, or when the version has no model and no model_override is given; 401 for a missing or invalid virtual key; 404 when the prompt, version or label does not exist, or the prompt has no default version and none is named; 422 when a guardrail blocks the request (x-guardrail-status: BLOCK). Provider errors are returned as on /v1/chat/completions.

Authorization

AuthorizationBearer <slug>.<secret>
A virtual key's API key (vk-....<secret>), as Authorization: Bearer. What the OpenAI SDK sends from its api_key. Used by the inference endpoints.
orx-virtual-keyheader
A virtual key's API key in the x-virtual-key header, for clients that keep Authorization for something else.
orx-api-keyheader
Direct credentials: the provider's own API key in x-api-key, with the provider named in x-provider (for example openai). On /v1/messages a virtual key is accepted in x-api-key too, which is what the Claude SDK sends.

Path parameters

slugstringrequired
the prompt's slug

Headers

x-cache-modestring
Turns on the response cache for this request: simple (exact match) or semantic (a similar earlier request). Without it nothing is read from or written to the cache. The outcome is in the x-cache-status response header.
x-cache-ttlinteger<int32>
How long, in seconds, a response stored by this request stays in the cache. When the organization has a cache TTL set, this can shorten it but not extend it.
x-cache-force-refreshboolean
true skips the cache lookup, calls the provider and replaces the stored response (x-cache-status: REFRESH).
x-guardrailstring
A guardrail slug (gr-...) to apply to this request, in addition to any the virtual key carries. A BLOCK is a 422 with x-guardrail-status: BLOCK.
x-configstring
A routing config slug: the config chooses the provider, model and key (load balancing, fallback or conditional routing). Without a virtual key, send x-organization with it to name the config's organization.

Request body application/json

the variables, the version and the streaming option

variablesmap<string, string>required
Values for the template's {{name}} placeholders, as a JSON object of strings. A placeholder with no value is sent to the model as written.
version_refstring
Which version to use: a version number (for example 3), latest (the highest version number, whatever its status) or @ followed by a label (for example @staging). Omit it for the default version: the one the production label points at, else the PUBLISHED version. An unknown version or label is a 404, any other value a 400.
streamboolean
true streams the answer as server-sent events. Default false.
model_overridestring
A model to use instead of the version's model. Required when the version has no model (400 otherwise).

Responses

200application/json

The model's answer, as a chat completion or, with stream: true, a stream of chat completion chunks.

idstring
The completion's id, as the provider assigned it.
objectstring
The object type, chat.completion.
createdinteger<int64>
When the completion was created, in Unix seconds.
modelstring
The model that produced the answer, as the provider reports it (it may carry a version suffix).
choicesobject[]
The answers, one per requested choice (n, default 1).
Child attributes
- indexinteger<int32>
  The choice's position in choices, from 0.
- messageobject
  One message of a conversation, in OpenAI's format: in a request, a turn of the conversation so far; in a response, the model's answer.
  Child attributes
  - roleenum<string>required
    Who wrote the message: system (instructions), user, assistant (the model) or tool (a tool call's result). Required.
    One of "system", "user", "assistant", "tool"
  - contentobject
    The message's content: a string, or an array of content parts (text, image_url, input_audio, file), each an object with a type. Any other shape is a 400 naming the message. May be null on an assistant message that only calls tools.
  - namestring
    An optional name for the author, to tell participants with the same role apart.
  - tool_callsobject[]
    On an assistant message: the tool calls the model made. Empty when it made none.
    Child attributes
    idstring
    The tool call id, sent back as tool_call_id on the tool message with the result.
    typestring
    Always function.
    functionobject
    The function a tool call invokes: its name and the arguments the model chose.
    Child attributes
    namestring
    The name of the function the model calls.
    argumentsstring
    The arguments, as a JSON string the model generated. Validate it before use: the model may produce invalid JSON or arguments the schema does not allow.
  - tool_call_idstring
    On a tool message: the id of the tool call this message answers.
  - thinking_blocksmap<string, object>[]
    Claude models with extended thinking: the assistant turn's reasoning blocks, {"type":"thinking","thinking":"...","signature":"..."} or {"type":"redacted_thinking","data":"..."}, each with a position among the message's other blocks. Send them back unchanged on the next request: Anthropic checks the signature and treats a dropped, edited or reordered block as an edited history. Absent when there are none.
  - is_errorboolean
    On a tool message: true when the tool call failed. Sent to Claude models as the tool result's error flag. Absent otherwise.
- finish_reasonenum<string>
  Why the model stopped: stop (a natural end or a stop sequence), length (the token limit), tool_calls or content_filter.
  One of "stop", "length", "content_filter", "tool_calls"
- stop_sequencestring
  The stop sequence that ended the turn, when one did (Anthropic's stop_sequence). OpenAI's finish_reason reports a stop sequence and a natural end alike as stop, so this is what lets /v1/messages answer stop_reason: stop_sequence. Set only by the Anthropic adapters; omitted from the body otherwise.
usageobject
The tokens a request used, in OpenAI's format. prompt_tokens counts every input token, including those read from or written to the provider's prompt cache.
Child attributes
- prompt_tokensinteger<int32>
  Input tokens, cached or not.
- completion_tokensinteger<int32>
  Output tokens the model generated.
- total_tokensinteger<int32>
  prompt_tokens plus completion_tokens.
- prompt_tokens_detailsobject
  OpenAI's usage.prompt_tokens_details. Only cached_tokens is carried: the input tokens read from the provider's prompt cache (OpenAI's automatic caching, Anthropic's cache_read_input_tokens). Other fields OpenAI adds (audio_tokens) are ignored.
  Child attributes
  - cached_tokensinteger<int32>
    Input tokens read from the provider's prompt cache.
- cache_creation_input_tokensinteger<int32>
  Input tokens written to the provider's prompt cache (Claude), part of prompt_tokens. Absent when none were reported.
- cache_creation_1h_input_tokensinteger<int32>
  Of cache_creation_input_tokens, those written with the 1-hour cache lifetime, which costs more than the 5-minute one. Absent when none were reported.

Request

curl -X POST "https://api.vectoraxis.ai/v1/prompts/{slug}/completions" \
  -H "Authorization: Bearer $VECTORAXIS_VIRTUAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "variables": {
    "key": "string"
  }
}'

Response 200

{
  "id": "string",
  "object": "string",
  "created": 0,
  "model": "string",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "system",
        "content": {},
        "name": "string",
        "tool_calls": [
          {}
        ],
        "tool_call_id": "string",
        "thinking_blocks": [
          {
            "key": {}
          }
        ],
        "is_error": true
      },
      "finish_reason": "stop",
      "stop_sequence": "string"
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0,
    "prompt_tokens_details": {
      "cached_tokens": 0
    },
    "cache_creation_input_tokens": 0,
    "cache_creation_1h_input_tokens": 0
  }
}

VectorAxis is built by GK Labs, a member of NVIDIA Inception.