Skip to content
helping.io
Get an API key

API reference

Create a response.

POST
/responses
curl --request POST \
  --url https://api.helping.io/v1/responses \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "background": true, "conversation": { "id": "example" }, "frequency_penalty": 1, "include": [ "reasoning.encrypted_content" ], "input": [ { "id": "example" } ], "instructions": "example", "max_output_tokens": 1, "max_tool_calls": 1, "metadata": "example", "model": "example", "parallel_tool_calls": true, "presence_penalty": 1, "previous_response_id": "example", "prompt_cache_key": "example", "reasoning": { "effort": "none", "summary": "concise" }, "safety_identifier": "example", "service_tier": "auto", "store": true, "stream": true, "stream_options": { "include_obfuscation": true }, "temperature": 1, "text": { "format": { "type": "text" }, "verbosity": "low" }, "tool_choice": "none", "tools": [ { "description": "example", "name": "example", "parameters": "example", "strict": true, "type": "function" } ], "top_logprobs": 1, "top_p": 1, "truncation": "auto", "user": "example" }'

Send input and a model, or continue an existing conversation with previous_response_id. The API keeps the history, so a later turn sends only the new input.

Set stream: true to receive server-sent events instead of one body. Without it the request waits a bounded time and, if the response is not finished by then, returns it in progress for you to retrieve by id.

To answer a tool call, send its result as a function_call_output item on the next turn, quoting the call_id from the call.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”

The response to create.

Media typeapplication/json

The body of a create-response request.

Fields you omit take their defaults, and fields this API does not recognize are ignored rather than refused, so a newer client stays compatible with an older server.

Every field of this body has one of four outcomes on this API: it is applied, it is refused with an error that names it, it is accepted and not applied, or it is advisory and the response reports what was applied rather than what you sent. The generation settings are applied when the model supports them, and refused with an error that names the model and the field when it does not.

truncation IS applied: disabled, the default, refuses a turn that will not fit the model’s context window, and auto lets the oldest turns be dropped so it fits.

The compatibility page says which outcome each field has, and its tables are generated from the same classification the server refuses from.

object
background

Runs the response in the background.

Not accepted today: background: true is refused. A non-streaming request that outlives its wait window already returns the response in progress for you to retrieve later, which covers the same need.

boolean
conversation
Any of:
One of:

The conversation’s opaque id.

string
frequency_penalty

Penalty applied in proportion to how often a token has appeared.

Applied when the model accepts it. When the model does not, or the value is outside the range the model accepts, the request is refused with an error that names the model and the field. The response reports the value it was generated with, and 0 when no penalty was applied.

number | null format: double
include

Extras to return that are omitted by default.

Array<string>
Allowed values: reasoning.encrypted_content message.output_text.logprobs message.input_image.image_url file_search_call.results web_search_call.results web_search_call.action.sources computer_call_output.output.image_url code_interpreter_call.outputs
input
Any of:
One of:
string
instructions

Steering text for this turn only.

Applies to this request and is not inherited by later turns.

string | null
max_output_tokens

Caps the tokens this response may produce.

The smallest accepted value is 16.

integer | null format: int64
max_tool_calls

Caps how many tool calls the model may make while generating this response.

Counts every tool call, not only built-in tools, across every turn of the response. Your organization’s policy also limits how many calls one turn may make. Calls past either limit are neither returned nor run, and helpingio:tool_calls_dropped on the response says how many were cut. The smallest accepted value is 1.

integer | null format: int64
metadata

Arbitrary metadata to attach, echoed back on the response.

model

The model to run, either bare or as provider/model.

string | null
parallel_tool_calls

Whether the model may request several tool calls at once.

Applied when the model accepts it. When the model does not, or the value is outside the range the model accepts, the request is refused with an error that names the model and the field. The response reports the value it was generated with, and true when none was set.

boolean | null
presence_penalty

Penalty applied to tokens that have already appeared.

Applied when the model accepts it. When the model does not, or the value is outside the range the model accepts, the request is refused with an error that names the model and the field. The response reports the value it was generated with, and 0 when no penalty was applied.

number | null format: double
previous_response_id

Continues the conversation that produced this response id.

The API keeps the history, so a later turn sends only the new input rather than replaying what came before.

string | null
prompt_cache_key

A key that groups requests which share a prompt prefix.

Advisory. What this API does with it is on the compatibility page.

string | null
reasoning
Any of:

Reasoning settings.

On a response this reports the settings that applied. This API does not accept it on a request: sending this field is refused rather than ignored.

object
effort
Any of:

How much reasoning the model should spend before answering.

Higher settings trade latency and cost for more deliberation. none disables reasoning where the model supports doing so.

string
Allowed values: none low medium high xhigh
summary
Any of:

How much of the model’s reasoning to summarize back to you, when a summary is produced at all.

string
Allowed values: concise detailed auto
safety_identifier

An opaque identifier for the end user this request is on behalf of, used to detect abuse by one end user without restricting your whole key.

Sent on the model calls this response makes for your request, where the model’s provider has a per-end-user field, as a keyed hash of your value rather than the value itself. The response reports the value you sent. A request that sends tool output keeps the value of the request that asked for the tool call.

string | null
service_tier
Any of:

The service tier a request asks for.

string
Allowed values: auto default flex priority
store

Whether the response is stored so it can be retrieved later.

Defaults to true, and true is the only value this API accepts today: store: false is refused rather than silently stored.

boolean
stream

Streams the response as server-sent events instead of returning it in one body.

boolean
stream_options
Any of:

Options that apply only when stream is true.

object
include_obfuscation

Pads each streamed delta event with an obfuscation string so the size of the event does not track the length of the text in it.

On unless you set it to false, which turns the padding off.

boolean | null
temperature

Sampling temperature.

Applied when the model accepts it. When the model does not, or the value is outside the range the model accepts, the request is refused with an error that names the model and the field. When you omit it, the model’s own default applies. The response reports the temperature it was generated with, and 1 when none was set.

number | null format: double
text
Any of:

Settings for the response text.

object
format
Any of:
One of:
object
type
required
string
Allowed values: text
verbosity
Any of:

How much detail to aim for in the response text.

string
Allowed values: low medium high
tool_choice
Any of:
One of:

The string form of tool_choice.

auto lets the model decide whether to call a tool, required makes it call one, and none forbids tool calls for this turn.

string
Allowed values: none auto required
tools

The tools the model may call on this turn.

Array | null
One of:

A tool offered to the model, discriminated by type.

object
description
string | null
name
required
string
parameters
strict
boolean | null
type
required
string
Allowed values: function
top_logprobs

How many alternative tokens to report log probabilities for.

No current model returns log probabilities, so a request that sets this is refused with an error that names the model and the field. The response reports 0.

integer | null format: int64
top_p

Nucleus sampling cutoff.

Applied when the model accepts it. When the model does not, or the value is outside the range the model accepts, the request is refused with an error that names the model and the field. When you omit it, the model’s own default applies. The response reports the value it was generated with, and 1 when none was set.

number | null format: double
truncation
Any of:

What to do when a conversation no longer fits the model’s context window.

auto lets the OLDEST turns be dropped so the request can proceed; disabled fails the request instead of dropping anything, and is the default (OpenAI’s default too).

Oldest-first is the same end OpenAI documents dropping from: their own API reference words auto as “dropping items from the beginning of the conversation”. The turn the caller just sent is never a candidate.

string
Allowed values: auto disabled
user

Deprecated in favor of safety_identifier.

When safety_identifier is absent, this value is used as it would be: the end user this request is on behalf of. When both are sent, safety_identifier is used. It does not group requests for caching.

string | null

Responses

Section titled “ Responses ”

200

Section titled “200”

The response. With stream: true the body is a server-sent event stream instead, whose events carry this same object at its terminal (see the StreamingEvent schema). A non-streaming request waits up to 90 seconds; if the response is not finished by then it is returned in progress, with the same id, a status of queued or in_progress, and an empty output, rather than as an error. It keeps running, so retrieve it by that id for the result. A streamed response has no such bound.

Media typeapplication/json

A response: one model turn, with everything it produced and the settings it ran under.

The settings are echoed back as they were applied, which is not always what you sent: values you omitted are filled in, and values capped by your organization’s policy are reported at the capped figure.

object
background
required
boolean
completed_at
required
integer | null format: int64
conversation
Any of:

The conversation a response belongs to.

Its items are the context the response ran on, and the response’s own input and output are added to it.

object
id
required

The conversation’s opaque id, conv_....

string
created_at
required
integer format: int64
error
required
Any of:

Why a response failed, carried on the response object itself.

A response that fails after it started is not an HTTP error: the request succeeds and the response object carries status: "failed" and this.

object
code
required
string
message
required
string
frequency_penalty
required
number format: double
id
required
string
incomplete_details
required
Any of:

Why a response stopped before it was finished.

object
reason
required
string
instructions
required
string | null
max_output_tokens
required
integer | null format: int64
max_tool_calls
required

The maximum number of tool calls this response was allowed to make.

The max_tool_calls sent with the request that started the turn, and null when that request sent none. A request that sends tool output keeps that value: a max_tool_calls sent with it is ignored.

integer | null format: int64
metadata
required

Whatever metadata you attached to the request, echoed back.

Always present, and null when you attached none.

model
required
string
object
required

Always response.

string
output
required
Array
One of:

One item of output, discriminated by type.

object
content
required
Array
One of:

Text you are sending to the model.

object
text
required
string
type
required
string
Allowed values: input_text
id
required
string
phase
Any of:

Whether an assistant message is the answer or commentary alongside it.

final_answer marks the message meant as the reply; commentary marks narration produced on the way there.

string
Allowed values: commentary final_answer
role
required

Who a message came from.

string
Allowed values: user assistant system developer
status
required

How far along an output item is.

in_progress while the item is still being produced, completed when it is final, and incomplete when the response stopped before the item was finished.

string
Allowed values: in_progress completed incomplete
type
required
string
Allowed values: message
parallel_tool_calls
required
boolean
presence_penalty
required
number format: double
previous_response_id
required
string | null
prompt_cache_key
required
string | null
reasoning
required
Any of:

Reasoning settings.

On a response this reports the settings that applied. This API does not accept it on a request: sending this field is refused rather than ignored.

object
effort
Any of:

How much reasoning the model should spend before answering.

Higher settings trade latency and cost for more deliberation. none disables reasoning where the model supports doing so.

string
Allowed values: none low medium high xhigh
summary
Any of:

How much of the model’s reasoning to summarize back to you, when a summary is produced at all.

string
Allowed values: concise detailed auto
safety_identifier
required
string | null
service_tier
required

The service tier this response ran under.

string
status
required

Where this response is in its lifecycle.

One of queued, in_progress, completed, failed, incomplete, or cancelled. queued and in_progress mean it is still running and can be retrieved again later; the rest are terminal. Treat it as an open string so a status added later does not break your client.

string
store
required
boolean
temperature
required
number format: double
text
required

Settings for the response text.

object
format
Any of:
One of:
object
type
required
string
Allowed values: text
verbosity
Any of:

How much detail to aim for in the response text.

string
Allowed values: low medium high
tool_choice
required
One of:

The string form of tool_choice.

auto lets the model decide whether to call a tool, required makes it call one, and none forbids tool calls for this turn.

string
Allowed values: none auto required
tools
required
Array
One of:

A tool offered to the model, discriminated by type.

object
description
string | null
name
required
string
parameters
strict
boolean | null
type
required
string
Allowed values: function
top_logprobs
required
integer format: int64
top_p
required
number format: double
truncation
required

What to do when a conversation no longer fits the model’s context window.

auto lets the OLDEST turns be dropped so the request can proceed; disabled fails the request instead of dropping anything, and is the default (OpenAI’s default too).

Oldest-first is the same end OpenAI documents dropping from: their own API reference words auto as “dropping items from the beginning of the conversation”. The turn the caller just sent is never a candidate.

string
Allowed values: auto disabled
usage

What this response consumed.

ABSENT while the response is still running, and present once it settles. A response that is queued or in_progress has spent nothing you can be billed for yet, so there is no figure to report, and the field is left out rather than sent as null.

object
input_tokens
required
integer format: int64
input_tokens_details
required

A breakdown of the input tokens counted.

Both fields are SUBSETS of input_tokens, not additions to it.

object
cache_write_tokens
required

Input tokens written INTO the provider’s prompt cache.

A provider that does not charge for a cache write reports 0 here.

integer format: int64
cached_tokens
required

Input tokens served from the provider’s prompt cache.

integer format: int64
output_tokens
required
integer format: int64
output_tokens_details
required

A breakdown of the output tokens counted.

object
reasoning_tokens
required
integer format: int64
total_tokens
required
integer format: int64
Example
{
  "output": [
    {
      "content": [
        {
          "type": "input_text"
        }
      ],
      "phase": "commentary",
      "role": "user",
      "status": "in_progress",
      "type": "message"
    }
  ],
  "reasoning": {
    "effort": "none",
    "summary": "concise"
  },
  "text": {
    "format": {
      "type": "text"
    },
    "verbosity": "low"
  },
  "tool_choice": "none",
  "tools": [
    {
      "type": "function"
    }
  ],
  "truncation": "auto"
}

400

Section titled “400”

Malformed body, unknown/ambiguous model, or unsupported parameter (the error envelope)

401

Section titled “401”

Missing or invalid API key (the error envelope)

402

Section titled “402”

The organization has no payment method on file, so nothing was started.

403

Section titled “403”

The key is not entitled to what the request asked for (the error envelope)

404

Section titled “404”

No such previous_response_id, or one this key cannot reach.

409

Section titled “409”

The Idempotency-Key was already used and its result cannot be returned for this request, or its first request is still being processed (the error envelope)

429

Section titled “429”

A rate limit, a spend budget or the organization’s credit balance refused this request, or the model provider rate limited it; the error code says which.

500

Section titled “500”

The request could not be completed; quote the x-request-id response header when reporting it.

502

Section titled “502”

The model provider did not complete the request; retry shortly.

503

Section titled “503”

The request could not be served this instant and nothing was created; retry after the Retry-After header.

504

Section titled “504”

The wait for a result ended before one was available and no response could be read back for it.

© 2026 helping.io