> ## Documentation Index
> Fetch the complete documentation index at: https://aidocs.ethanbragdon.icu/llms.txt
> Use this file to discover all available pages before exploring further.

# Responses API Reference

> Reference Starfire-native response creation, model input, reasoning/tool options, streaming, usage, and transition to long-running runs.

# Responses API reference

The Starfire-native Responses resource is designed for workloads that need richer Starfire capabilities than the compatibility chat endpoint can express.

## Resource

The Alpha v1 architecture includes:

```http theme={null}
POST /v1/responses
```

The active OpenAPI/Developer Portal defines the exact schema and enabled fields.

## Response inputs

The native request model can carry concepts such as:

* model or routing preference
* input/messages
* reasoning configuration
* tools
* structured-output requirements
* project or organization context
* streaming preference

## Synchronous vs run-backed work

A normal response can complete within one request/stream. Work that can take materially longer—such as deep research or FORGE—should use a durable run/build resource instead of holding one request open indefinitely.

## Tools

Tool use is constrained by model capability, developer scope, plan, organization policy, and tool configuration.

A request cannot grant itself a tool simply by naming it in the payload if the credential/context is not eligible.

## Usage

The response can contribute to the same Starfire metering foundation as web usage while remaining visible as Developer Platform usage.

## Request ID

Capture the request identifier returned by Starfire for support and log correlation.

## Structured output

When the active model/route supports schema-constrained output, validate the resulting object in your application before acting on it.

<Note>
  Use the native Responses resource when you want Starfire's platform semantics. Use compatibility endpoints when interoperability with an existing client contract is the primary goal.
</Note>