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

# Responses API

> Start here for new NagaAI LLM integrations.

<Tip>
  **Recommended** Use `Responses API` for new LLM integrations.
</Tip>

`Responses API` is the main LLM surface on NagaAI. Start here when you want one API for plain text, tools, structured outputs, streaming, reasoning, and multimodal inputs.

## Best Fit

* new LLM features without legacy protocol constraints
* typed output flows such as tool calls and reasoning items
* multimodal prompts that mix text with images, files, or audio
* streaming clients that want semantic event names instead of chat chunks

## Request Model

Most requests start with:

* `model`
* `input`
* `instructions`
* `tools`
* `text`
* `reasoning`
* `stream`

## Quick Example

<CodeGroup>
  ```python Python theme={null}
  from openai import OpenAI

  client = OpenAI(
      base_url="https://api.naga.ac/v1",
      api_key="YOUR_API_KEY",
  )

  response = client.responses.create(
      model="gpt-4.1-mini",
      input="Summarize why observability matters in production systems.",
  )

  print(response.output_text)
  ```

  ```javascript Node.js theme={null}
  import OpenAI from 'openai';

  const client = new OpenAI({
    baseURL: 'https://api.naga.ac/v1',
    apiKey: 'YOUR_API_KEY',
  });

  const response = await client.responses.create({
    model: 'gpt-4.1-mini',
    input: 'Summarize why observability matters in production systems.',
  });

  console.log(response.output_text);
  ```

  ```bash cURL theme={null}
  curl https://api.naga.ac/v1/responses \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-4.1-mini",
      "input": "Summarize why observability matters in production systems."
    }'
  ```
</CodeGroup>

## Response Model

Successful responses are `response` objects with typed `output[]` items.

```json theme={null}
{
  "object": "response",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Observability helps teams detect, explain, and fix production failures faster.",
          "annotations": [],
          "logprobs": []
        }
      ]
    }
  ]
}
```

Do not assume `output[0]` is always the final answer. The array can also contain `reasoning`, `function_call`, and other typed items.

## Learn The API In Detail

<CardGroup cols={2}>
  <Card title="Text Generation" icon="file-lines" href="/api/responses/text-generation">
    Start with the simplest request and response flow.
  </Card>

  <Card title="Streaming" icon="signal" href="/api/responses/streaming">
    Parse semantic SSE events and final snapshots correctly.
  </Card>

  <Card title="Tool Calling" icon="wrench" href="/api/responses/tool-calling">
    Work with `function_call` and `function_call_output` items.
  </Card>

  <Card title="Structured Outputs" icon="brackets-curly" href="/api/responses/structured-outputs">
    Use `text.format` for schema-shaped output.
  </Card>
</CardGroup>

<CardGroup cols={2}>
  <Card title="Reasoning" icon="brain" href="/api/responses/reasoning">
    Control and inspect reasoning items.
  </Card>

  <Card title="Multimodal Inputs" icon="shapes" href="/api/responses/multimodal-inputs">
    Send images, files, and audio through typed input parts.
  </Card>

  <Card title="Web Search" icon="search" href="/api/responses/web-search">
    Enable search through the public web-search tool shape.
  </Card>

  <Card title="Conversation State" icon="clock-rotate-left" href="/api/responses/conversation-state">
    Model multi-turn state in a stateless gateway environment.
  </Card>
</CardGroup>

## Use Another API Only When Needed

* use [Chat Completions API](/api/chat-completions) when you need OpenAI chat compatibility
* use [Messages API](/api/messages) when you need Anthropic compatibility
* use [Embeddings API](/api/embeddings), [Audio API](/api/audio), [Images API](/api/images), or [Moderations API](/api/moderations) for those dedicated workflows

## Reference

* [Create response](/api-reference/endpoints/responses/create)