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

# Responses API Contract

> How Agnitra integrates with the OpenAI Responses API for optimization hints and telemetry enrichment.

# Responses API Contract

Agnitra uses the OpenAI Responses API to translate profiler telemetry into kernel tuning recommendations. This reference covers request schemas, tooling payloads, and operational guardrails.

## Base URL

```
https://api.openai.com/v1/responses
```

All calls must be made over HTTPS.

## Authentication

| Header                | Value                                                                |
| --------------------- | -------------------------------------------------------------------- |
| `Authorization`       | `Bearer <OPENAI_API_KEY>`                                            |
| `OpenAI-Project`      | Optional. Overrides the project context associated with the API key. |
| `OpenAI-Organization` | Optional. Use when the key belongs to multiple organisations.        |

Store API keys in a secrets manager or environment variable. Never expose them in client-side code.

## Request Schema

```json theme={null}
{
  "model": "gpt-5-codex",
  "input": [
    { "role": "system", "content": "Provide kernel tuning recommendations for the supplied telemetry." },
    { "role": "user", "content": "Telemetry summary: {...}" }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "record_patch_plan",
        "description": "Persist selected kernel parameters.",
        "parameters": {
          "type": "object",
          "properties": {
            "block_size": { "type": "integer" },
            "tile_shape": {
              "type": "array",
              "items": { "type": "integer" },
              "minItems": 2,
              "maxItems": 2
            },
            "expected_latency_ms": { "type": "number" }
          },
          "required": ["block_size", "tile_shape", "expected_latency_ms"]
        }
      }
    }
  ],
  "metadata": {
    "project_id": "demo",
    "model_name": "tinyllama",
    "target": "A100"
  }
}
```

* `model` must reference a Responses-capable deployment (e.g. `gpt-5-codex` or `gpt-5-mini`). Do not use deprecated parameters such as `temperature` or `max_output_tokens`.
* `input` accepts text or image content. Agnitra sends JSON-formatted telemetry snippets.
* `tools` unlock structured responses via function calling; strict schemas avoid invalid payloads.
* `metadata` captures attribution for usage metering and billing.

## Response Structure

```json theme={null}
{
  "id": "resp_123",
  "usage": { "total_tokens": 512 },
  "output": [
    {
      "role": "assistant",
      "content": [
        { "type": "output_text", "text": "Suggested block size: 128 ..." }
      ]
    }
  ],
  "tool_calls": [
    {
      "type": "function",
      "function": {
        "name": "record_patch_plan",
        "arguments": "{\"block_size\":128,\"tile_shape\":[64,64]}"
      }
    }
  ]
}
```

* Parse `tool_calls` and validate against the schema before mutating kernels.
* `usage.total_tokens` feeds into Agnitra’s cost telemetry pipeline.

## Rate Limits & Diagnostics

* Inspect `x-ratelimit-*` headers to understand remaining token/request budgets.
* Log the `x-request-id` header for each call to accelerate support escalation.
* Retry with exponential backoff on `429` and `5xx` responses; avoid retrying validation errors.

## Error Handling

| Status                  | Typical Cause                        | Resolution                                              |
| ----------------------- | ------------------------------------ | ------------------------------------------------------- |
| `400 Bad Request`       | Invalid JSON schema or tool payload. | Inspect error body, correct request data.               |
| `401 Unauthorized`      | API key missing/invalid.             | Refresh credentials and retry.                          |
| `403 Forbidden`         | Project/org mismatch.                | Confirm `OpenAI-Project`/`OpenAI-Organization` headers. |
| `429 Too Many Requests` | Rate limit exceeded.                 | Use `Retry-After` header and exponential backoff.       |
| `500`/`503`             | Upstream transient error.            | Retry with jitter (max 3 attempts).                     |

## Security Checklist

* Rotate API keys regularly and scope them to the minimum required access.
* Sanitize telemetry content to avoid leaking customer identifiers.
* Validate every tool-call payload against the defined JSON schema prior to execution.

## Related Documentation

* [Runtime Configuration](/docs/reference/configuration) — environment variables that toggle Responses API usage.
* [SDK & CLI Guide](/docs/guides/cli-and-sdk) — how responses inform local optimisation flows.
* [Architecture Overview](/docs/intro/architecture) — where Responses API fits in the optimization loop.