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.

background: true is rejected. Generation runs in the request.

Create a response

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)

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
  }'

A completed body looks like:

{
  "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 for how the connection behaves.

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)

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
  }'

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.

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)

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
  }'

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.

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 instead of calling tools from the Responses API yourself.

Getting started

Products

Guides

Examples

Manage

Platform

Resources

Support

Legal

Create a response

Stream

Store a response and continue it

Tools

​Create a response

​Stream

​Store a response and continue it

​Tools

Create a response

Stream

Store a response and continue it

Tools