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

# Responses API

> Create, stream, continue, retrieve, and delete responses with the OpenAI-compatible Responses API

`POST /v1/responses` is the OpenAI Responses API for models deployed on SynapsAI Cloud. Use it when you want a single `input` field, optional instructions, tools, and a typed `output` array.

`input` may be a string or a list of message and content items. Replace `model-id` with your deployment's model ID.

<Note>
  `background: true` is rejected. Generation runs in the request.
</Note>

## Create a response

<CodeGroup>
  ```python title="Python" theme={null}
  from synapsai import SynapsAI

  client = SynapsAI()

  response = client.responses.create(
      model="model-id",
      input="Explain retrieval-augmented generation in one paragraph.",
      instructions="Answer in plain language.",
      temperature=0.2,
  )
  print(response.id)
  print(response.output_text)
  ```

  ```bash title="cURL" theme={null}
  curl https://api.synapsai.cloud/v1/responses \
    -H "Authorization: Bearer $SYNAPSAI_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "model-id",
      "instructions": "Answer in plain language.",
      "input": "Explain retrieval-augmented generation in one paragraph.",
      "temperature": 0.2
    }'
  ```
</CodeGroup>

A completed body looks like:

```json theme={null}
{
  "id": "resp_abc123",
  "object": "response",
  "status": "completed",
  "model": "model-id",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {"type": "output_text", "text": "Retrieval-augmented generation ..."}
      ]
    }
  ],
  "output_text": "Retrieval-augmented generation ..."
}
```

## Stream

Set `stream` to `true`. The response is Server-Sent Events. See [Streaming](/guides/streaming) for how the connection behaves.

<CodeGroup>
  ```python title="Python" theme={null}
  for event in client.responses.create(
      model="model-id",
      input="Count to five.",
      stream=True,
  ):
      if event.type == "response.output_text.delta" and event.delta:
          print(event.delta, end="", flush=True)
      elif event.type == "response.completed" and event.response:
          print("\n", event.response.id)
  ```

  ```bash title="cURL" theme={null}
  curl https://api.synapsai.cloud/v1/responses \
    -H "Authorization: Bearer $SYNAPSAI_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Accept: text/event-stream" \
    -N \
    -d '{
      "model": "model-id",
      "input": "Count to five.",
      "stream": true
    }'
  ```
</CodeGroup>

## Store a response and continue it

Persistence follows the model data store. When data store is enabled on the deployment, the response is stored unless you send `"store": false`. When data store is off, nothing is saved.

`previous_response_id` loads the stored chain and appends the new `input`. SynapsAI strips that id before the model sees the request. The chain must belong to your account, must not cycle, and must stay within the platform depth limit.

<CodeGroup>
  ```python title="Python" theme={null}
  first = client.responses.create(
      model="model-id",
      input="Explain RAG in one paragraph.",
      store=True,
      metadata={"topic": "rag"},
  )

  follow_up = client.responses.create(
      model="model-id",
      input="Give a shorter version.",
      previous_response_id=first.id,
      store=True,
  )
  print(follow_up.output_text)

  stored = client.responses.retrieve(first.id)
  client.responses.delete(first.id)
  ```

  ```bash title="cURL" theme={null}
  curl https://api.synapsai.cloud/v1/responses \
    -H "Authorization: Bearer $SYNAPSAI_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "model-id",
      "input": "Give a shorter version.",
      "previous_response_id": "resp_abc123",
      "store": true
    }'
  ```
</CodeGroup>

Retrieve and delete:

| Method | Path | Result |
| - | - | - |
| `GET` | `/v1/responses/{response_id}` | The stored response object |
| `DELETE` | `/v1/responses/{response_id}` | `{ "id", "object": "response.deleted", "deleted": true }` |

A missing id returns 404.

You can also pass prior turns yourself with `previous_input_messages` when you do not want the server to look up a stored response.

## Tools

`tools`, `tool_choice`, and `parallel_tool_calls` match the chat completions tool shape. For a full tool-calling walkthrough on chat completions, see [Tool calling](/examples/tool-calling).

```python theme={null}
response = client.responses.create(
    model="model-id",
    input="What is 17 * 23?",
    tools=[
        {
            "type": "function",
            "name": "calculator",
            "description": "Evaluate an arithmetic expression",
            "parameters": {
                "type": "object",
                "properties": {
                    "expression": {"type": "string"}
                },
                "required": ["expression"],
            },
        }
    ],
)
```

For a multi-step loop with built-in tools and knowledge bases, use an [agent](/guides/agents) instead of calling tools from the Responses API yourself.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.