Use Responses and Conversations

The Responses API is an OpenAI-compatible interface for text and image input, function calling, structured output, streaming, and durable conversation state. It is available at https://api.provod.ai/v1 and uses the same Bearer API key and model IDs as the other API formats.

Create a response

Choose an available text model from GET /v1/models, then start with one non-streaming request:

export PROVOD_API_KEY="sk_..."

curl --fail-with-body --silent --show-error https://api.provod.ai/v1/responses \
  -H "Authorization: Bearer $PROVOD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4",
    "input": "Reply with ok"
  }'

Read assistant text from the output array. A text response contains an assistant message with one or more output_text parts:

{
  "id": "resp_example",
  "object": "response",
  "status": "completed",
  "model": "openai/gpt-5.4",
  "output": [
    {
      "id": "msg_example",
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [{ "type": "output_text", "text": "ok", "annotations": [] }]
    }
  ]
}

Responses supports portable state with previous_response_id and Conversations.

Continue a previous response

Responses are stored by default. Send the returned ID as previous_response_id when the next request should include the previous portable input and output history:

curl --fail-with-body --silent --show-error https://api.provod.ai/v1/responses \
  -H "Authorization: Bearer $PROVOD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4",
    "previous_response_id": "resp_example",
    "input": "Now answer with one word"
  }'

Use either previous_response_id or conversation in a request, not both. Retrieve an earlier stored response with GET /v1/responses/{response_id}, inspect its original portable input with GET /v1/responses/{response_id}/input_items, or delete stored state with DELETE /v1/responses/{response_id}.

Add an Idempotency-Key header when a network retry must not create a second stored response. Reusing the key with the same request returns the original response; do not reuse it for a different body.

Stream response events

Set stream to true to receive Responses Server-Sent Events (SSE). Process events in sequence and treat only a terminal response.completed, response.failed, or response.incomplete event as final:

curl --no-buffer --fail-with-body --silent --show-error https://api.provod.ai/v1/responses \
  -H "Authorization: Bearer $PROVOD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4",
    "input": "Reply with ok",
    "stream": true
  }'

data: {"type":"response.created","sequence_number":1,"response":{"id":"resp_example","status":"in_progress"}}

data: {"type":"response.output_text.delta","sequence_number":5,"item_id":"msg_example","output_index":0,"content_index":0,"delta":"ok"}

data: {"type":"response.completed","sequence_number":8,"response":{"id":"resp_example","status":"completed"}}

A connection close without a terminal event is incomplete. Retry with bounded backoff only before output was delivered; after a text, tool-call, or reasoning event arrives, preserve the partial result and let the caller decide whether to continue.

Use function tools and structured output

Pass portable function tools in tools. When the model returns a function_call, execute it in your application, then send a function_call_output item in the next request. Function execution stays in your environment; provod.ai does not run arbitrary client code.

Use text.format with json_object or json_schema for supported structured-output requests. Check the selected model's current supported_parameters in GET /v1/models; model availability and optional capabilities can change.

Keep a named Conversation

Conversations are separate durable objects for a sequence of portable input and output items. Create one, then pass its ID as conversation to POST /v1/responses:

export PROVOD_CONVERSATION_ID="$(
  curl --fail-with-body --silent --show-error https://api.provod.ai/v1/conversations \
    -H "Authorization: Bearer $PROVOD_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"metadata":{"project":"support-bot"}}' \
  | jq -r '.id'
)"

curl --fail-with-body --silent --show-error https://api.provod.ai/v1/responses \
  -H "Authorization: Bearer $PROVOD_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"model\":\"openai/gpt-5.4\",\"conversation\":\"$PROVOD_CONVERSATION_ID\",\"input\":\"Reply with ok\"}"

Use GET, POST, and DELETE on /v1/conversations/{conversation_id} to retrieve, update metadata, or delete a Conversation. Its items are available at /v1/conversations/{conversation_id}/items; append up to 20 portable items with POST, and use after, limit, and order to page through them.

Compatibility boundary

The portable API accepts text and image input, function tools, tool results, response chaining, Conversations, and the documented request fields on this page. It intentionally rejects hosted tools and provider-private state: web_search, file_search, code_interpreter, computer use, hosted MCP, background jobs, and encrypted provider-native reasoning state.

Troubleshooting