API reference
Add items to a conversation.
const url = 'https://api.helping.io/v1/conversations/example/items';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"items":[{"id":"example"}]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.helping.io/v1/conversations/example/items \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "items": [ { "id": "example" } ] }'Up to 20 per call. Added items become part of the conversation’s context: the next response on it sees them.
The answer is the items you just added, not the whole conversation.
Authorizations
Section titled “Authorizations”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters”The opaque conv_... id of the conversation
Query Parameters
Section titled “Query Parameters”Extras to return that are omitted by default.
Request Bodyrequired
Section titled “Request Bodyrequired”The items to add.
Add items to a conversation.
object
The items to add, up to 20 per call.
An input item, discriminated by type.
object
A message item, discriminated by role.
object
Text you are sending to the model.
object
Text the model produced.
annotations carries any citations for spans of this text.
logprobs carries per-token log probabilities; it is an empty array on
every response this surface produces today, because log probabilities
are never requested from a provider.
object
An annotation attached to a span of output text.
object
The log probability of one output token.
This surface does not produce log probabilities yet: top_logprobs is
accepted and not applied, and include: ["message.output_text.logprobs"]
is accepted and not acted on, so the logprobs arrays that carry this
type are empty on every response today. They are arrays rather than nulls
because the schema requires an array, and an empty one is the honest
answer for “none were produced”.
object
One alternative token the model considered, with its log probability.
object
Plain text, where neither direction is implied.
object
A summary of the model’s reasoning.
object
Reasoning text produced by the model.
object
The model declined to answer, and why.
object
An image you are sending to the model.
image_url accepts a URL or a data URL. detail asks for a
fidelity; omit it to let the model choose.
A file you are sending to the model, by URL or inline contents.
object
A video you are sending to the model.
object
A message item, discriminated by role.
object
Text you are sending to the model.
object
Text the model produced.
annotations carries any citations for spans of this text.
logprobs carries per-token log probabilities; it is an empty array on
every response this surface produces today, because log probabilities
are never requested from a provider.
object
An annotation attached to a span of output text.
object
The log probability of one output token.
This surface does not produce log probabilities yet: top_logprobs is
accepted and not applied, and include: ["message.output_text.logprobs"]
is accepted and not acted on, so the logprobs arrays that carry this
type are empty on every response today. They are arrays rather than nulls
because the schema requires an array, and an empty one is the honest
answer for “none were produced”.
object
One alternative token the model considered, with its log probability.
object
Plain text, where neither direction is implied.
object
A summary of the model’s reasoning.
object
Reasoning text produced by the model.
object
The model declined to answer, and why.
object
An image you are sending to the model.
image_url accepts a URL or a data URL. detail asks for a
fidelity; omit it to let the model choose.
A file you are sending to the model, by URL or inline contents.
object
A video you are sending to the model.
object
A message item, discriminated by role.
object
Text you are sending to the model.
object
Text the model produced.
annotations carries any citations for spans of this text.
logprobs carries per-token log probabilities; it is an empty array on
every response this surface produces today, because log probabilities
are never requested from a provider.
object
An annotation attached to a span of output text.
object
The log probability of one output token.
This surface does not produce log probabilities yet: top_logprobs is
accepted and not applied, and include: ["message.output_text.logprobs"]
is accepted and not acted on, so the logprobs arrays that carry this
type are empty on every response today. They are arrays rather than nulls
because the schema requires an array, and an empty one is the honest
answer for “none were produced”.
object
One alternative token the model considered, with its log probability.
object
Plain text, where neither direction is implied.
object
A summary of the model’s reasoning.
object
Reasoning text produced by the model.
object
The model declined to answer, and why.
object
An image you are sending to the model.
image_url accepts a URL or a data URL. detail asks for a
fidelity; omit it to let the model choose.
A file you are sending to the model, by URL or inline contents.
object
A video you are sending to the model.
object
A message item, discriminated by role.
object
Text you are sending to the model.
object
Text the model produced.
annotations carries any citations for spans of this text.
logprobs carries per-token log probabilities; it is an empty array on
every response this surface produces today, because log probabilities
are never requested from a provider.
object
An annotation attached to a span of output text.
object
The log probability of one output token.
This surface does not produce log probabilities yet: top_logprobs is
accepted and not applied, and include: ["message.output_text.logprobs"]
is accepted and not acted on, so the logprobs arrays that carry this
type are empty on every response today. They are arrays rather than nulls
because the schema requires an array, and an empty one is the honest
answer for “none were produced”.
object
One alternative token the model considered, with its log probability.
object
Plain text, where neither direction is implied.
object
A summary of the model’s reasoning.
object
Reasoning text produced by the model.
object
The model declined to answer, and why.
object
An image you are sending to the model.
image_url accepts a URL or a data URL. detail asks for a
fidelity; omit it to let the model choose.
A file you are sending to the model, by URL or inline contents.
object
A video you are sending to the model.
object
An input item, discriminated by type.
object
An input item, discriminated by type.
object
Text you are sending to the model.
object
Text the model produced.
annotations carries any citations for spans of this text.
logprobs carries per-token log probabilities; it is an empty array on
every response this surface produces today, because log probabilities
are never requested from a provider.
object
An annotation attached to a span of output text.
object
The log probability of one output token.
This surface does not produce log probabilities yet: top_logprobs is
accepted and not applied, and include: ["message.output_text.logprobs"]
is accepted and not acted on, so the logprobs arrays that carry this
type are empty on every response today. They are arrays rather than nulls
because the schema requires an array, and an empty one is the honest
answer for “none were produced”.
object
One alternative token the model considered, with its log probability.
object
Plain text, where neither direction is implied.
object
A summary of the model’s reasoning.
object
Reasoning text produced by the model.
object
The model declined to answer, and why.
object
An image you are sending to the model.
image_url accepts a URL or a data URL. detail asks for a
fidelity; omit it to let the model choose.
A file you are sending to the model, by URL or inline contents.
object
A video you are sending to the model.
object
An input item, discriminated by type.
object
Text you are sending to the model.
object
Text the model produced.
annotations carries any citations for spans of this text.
logprobs carries per-token log probabilities; it is an empty array on
every response this surface produces today, because log probabilities
are never requested from a provider.
object
An annotation attached to a span of output text.
object
The log probability of one output token.
This surface does not produce log probabilities yet: top_logprobs is
accepted and not applied, and include: ["message.output_text.logprobs"]
is accepted and not acted on, so the logprobs arrays that carry this
type are empty on every response today. They are arrays rather than nulls
because the schema requires an array, and an empty one is the honest
answer for “none were produced”.
object
One alternative token the model considered, with its log probability.
object
Plain text, where neither direction is implied.
object
A summary of the model’s reasoning.
object
Reasoning text produced by the model.
object
The model declined to answer, and why.
object
An image you are sending to the model.
image_url accepts a URL or a data URL. detail asks for a
fidelity; omit it to let the model choose.
A file you are sending to the model, by URL or inline contents.
object
A video you are sending to the model.
object
An input item, discriminated by type.
object
A pointer to an item that already exists, by id.
object
Responses
Section titled “ Responses ”The items that were added.
A page of a conversation’s items.
first_id and last_id are always present, as empty strings on an empty
page. A client paginating with after uses last_id, and has_more is what
tells it whether to ask again.
object
The items, in the order you asked for.
One item of output, discriminated by type.
object
Text you are sending to the model.
object
Text the model produced.
annotations carries any citations for spans of this text.
logprobs carries per-token log probabilities; it is an empty array on
every response this surface produces today, because log probabilities
are never requested from a provider.
object
An annotation attached to a span of output text.
object
The log probability of one output token.
This surface does not produce log probabilities yet: top_logprobs is
accepted and not applied, and include: ["message.output_text.logprobs"]
is accepted and not acted on, so the logprobs arrays that carry this
type are empty on every response today. They are arrays rather than nulls
because the schema requires an array, and an empty one is the honest
answer for “none were produced”.
object
One alternative token the model considered, with its log probability.
object
Plain text, where neither direction is implied.
object
A summary of the model’s reasoning.
object
Reasoning text produced by the model.
object
The model declined to answer, and why.
object
An image you are sending to the model.
image_url accepts a URL or a data URL. detail asks for a
fidelity; omit it to let the model choose.
A file you are sending to the model, by URL or inline contents.
object
A video you are sending to the model.
object
Who a message came from.
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.
One item of output, discriminated by type.
object
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.
One item of output, discriminated by type.
object
Text you are sending to the model.
object
Text the model produced.
annotations carries any citations for spans of this text.
logprobs carries per-token log probabilities; it is an empty array on
every response this surface produces today, because log probabilities
are never requested from a provider.
object
An annotation attached to a span of output text.
object
The log probability of one output token.
This surface does not produce log probabilities yet: top_logprobs is
accepted and not applied, and include: ["message.output_text.logprobs"]
is accepted and not acted on, so the logprobs arrays that carry this
type are empty on every response today. They are arrays rather than nulls
because the schema requires an array, and an empty one is the honest
answer for “none were produced”.
object
One alternative token the model considered, with its log probability.
object
Plain text, where neither direction is implied.
object
A summary of the model’s reasoning.
object
Reasoning text produced by the model.
object
The model declined to answer, and why.
object
An image you are sending to the model.
image_url accepts a URL or a data URL. detail asks for a
fidelity; omit it to let the model choose.
A file you are sending to the model, by URL or inline contents.
object
A video you are sending to the model.
object
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.
One item of output, discriminated by type.
object
Text you are sending to the model.
object
Text the model produced.
annotations carries any citations for spans of this text.
logprobs carries per-token log probabilities; it is an empty array on
every response this surface produces today, because log probabilities
are never requested from a provider.
object
An annotation attached to a span of output text.
object
The log probability of one output token.
This surface does not produce log probabilities yet: top_logprobs is
accepted and not applied, and include: ["message.output_text.logprobs"]
is accepted and not acted on, so the logprobs arrays that carry this
type are empty on every response today. They are arrays rather than nulls
because the schema requires an array, and an empty one is the honest
answer for “none were produced”.
object
One alternative token the model considered, with its log probability.
object
Plain text, where neither direction is implied.
object
A summary of the model’s reasoning.
object
Reasoning text produced by the model.
object
The model declined to answer, and why.
object
An image you are sending to the model.
image_url accepts a URL or a data URL. detail asks for a
fidelity; omit it to let the model choose.
A file you are sending to the model, by URL or inline contents.
object
A video you are sending to the model.
object
Text you are sending to the model.
object
Text the model produced.
annotations carries any citations for spans of this text.
logprobs carries per-token log probabilities; it is an empty array on
every response this surface produces today, because log probabilities
are never requested from a provider.
object
An annotation attached to a span of output text.
object
The log probability of one output token.
This surface does not produce log probabilities yet: top_logprobs is
accepted and not applied, and include: ["message.output_text.logprobs"]
is accepted and not acted on, so the logprobs arrays that carry this
type are empty on every response today. They are arrays rather than nulls
because the schema requires an array, and an empty one is the honest
answer for “none were produced”.
object
One alternative token the model considered, with its log probability.
object
Plain text, where neither direction is implied.
object
A summary of the model’s reasoning.
object
Reasoning text produced by the model.
object
The model declined to answer, and why.
object
An image you are sending to the model.
image_url accepts a URL or a data URL. detail asks for a
fidelity; omit it to let the model choose.
A file you are sending to the model, by URL or inline contents.
object
A video you are sending to the model.
object
The id of the first item on this page.
Whether more items exist after this page.
Items on this page that are stored but could not be read. The other
items are returned in data. Omitted when every item was read.
An item that is stored but could not be read.
object
Always item_unreadable.
The item’s id. Retrieving it returns the same error.
What went wrong.
The id of the last item on this page; pass it as after for the next
page.
Always list.
Example
{ "data": [ { "content": [ { "type": "input_text" } ], "phase": "commentary", "role": "user", "status": "in_progress", "type": "message" } ]}More than 20 items, or an item this API cannot store (the error envelope)
Missing or invalid API key (the error envelope)
The key is not entitled to what the request asked for (the error envelope)
No such conversation, or one this key cannot reach.
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)
This organization has exhausted its allowance; retry after the Retry-After header.
The request could not be completed; quote the x-request-id response header when reporting it.
The request could not be served this instant; retry after the Retry-After header.