Skip to content
API Reference

Make a Direct AI Request

Version: unreleased · Docs: 3c6ab9f2Download Markdown

Use POST /api/v1/inference/requests for a single model response. Redbelt keeps the thread and its history for you. The request goes straight to the model you choose, with no agent, tools or plugins.

Authenticate as described in the API quickstart. Call GET /api/v1/models, choose an available slug, and generate a UUIDv7 for request_id. Keep the exact request body and ID for retries. Auto is not a direct inference model; use an agent run for agent routing.

POST /api/v1/inference/requests
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
{
"request_id": "YOUR_UUIDV7",
"model": "AVAILABLE_MODEL_SLUG",
"input": "Summarize the following project update in three bullets: the design review is complete, implementation starts Monday, and the launch checklist needs an owner.",
"max_output_tokens": 1024
}

202 returns id, thread_id, kind: “inference”, and status. Read GET /api/v1/inference/requests/REQUEST_ID for the saved result. output contains text; partial distinguishes incomplete text from a completed answer.

Wait for a terminal result, then send a new UUIDv7 request_id, the returned thread_id, and new input. Do not send a transcript. The request uses the selected model and optional system_instructions for that turn.

Only the thread’s owner can continue it. One active input is allowed per thread; conflicting concurrent inputs return 409. Exact retries reuse the accepted request, while changed bodies under the same ID return 409.

Set output_format: “json”. Optional output_schema is a bounded JSON Schema with type: “object”. References ($ref and $dynamicRef) are unsupported. For example:

{
"type": "object",
"properties": { "summary": { "type": "string" } },
"required": ["summary"],
"additionalProperties": false
}

A completed JSON result includes structured_output. Invalid or incomplete JSON is a failed result, with retained partial text where available. Unsupported request fields are rejected; Redbelt does not silently replace your model.

A direct thread holds at most 20 turns and must fit the model’s context and output limits. Start a new thread when you reach a limit. Redbelt checks model availability and your spending limit again before sending each request.

GET /api/v1/inference/requests/REQUEST_ID?wait=30 holds the request until the result is final, or for up to 30 seconds, then returns the saved snapshot. While it runs, output holds the text generated so far. Closing a request does not cancel the work. Use POST /api/v1/inference/requests/REQUEST_ID/cancel to cancel explicitly.

Rarely, Redbelt can’t tell whether the model finished, for example after an interruption. The result then reports inference_outcome_unknown with any partial output. Redbelt doesn’t repeat the request automatically, so check the result before sending another.

See Track Runs and Retrieve Results for shared lifecycle rules.