Response-Agent API

The Response-Agent endpoint is used to communicate with your agent.
Use it to send a message and it returns the agent's response.

Endpoint
POST /v1/response-agent

Authentication

Every request must include your API key as a Bearer token in the Authorization header:

Authorization header
Bearer <your-api-key>

You can generate and manage keys on the API Keys page.

Request Body

Send a JSON body with the following fields. agent_id, session_id, client_prompt, environment, and client_platform are required; the rest are optional.

Field	Type	Required	Description
agent_id	string	Yes	Which agent should handle the request. See format.
session_id	string	Yes	The ID of the session this message belongs to.
client_prompt	string	Yes	The message to the agent.
environment	string	Yes	Which agent build to use. See values.
client_platform	string	Yes	Where the request comes from. See values.
reset_session	string	No	Whether to start fresh or continue. See values.
extra_context	object	No	Additional context for the agent to consider. See extra_context.

Field Details

agent_id

The identifier of the agent that should answer. It's always the letters pa- followed by exactly six digits—for example pa-123456. You'll find your agent's ID in Agent Studio.

environment

Selects which of your two agent configurations the request should use—matching the environment toggle in Agent Studio.

• live — Load the agent build from your live environment.
• test — Load the agent build from your test environment.

client_platform

Identifies the platform that sends the request. It accepts exactly two values, and no others.

• bubble — The request comes from a Bubble app.
• unlisted — The request comes from anywhere else. Use this for a custom backend, a script, or any platform not named above.

Different platforms hold a request open for different lengths of time, so this field sets how long your agent is allowed to run. bubble gets 2 minutes because Bubble's API Connector closes the connection at its own limit no matter what we do; unlisted gets 10 minutes.

Pick the value that matches where the request is actually sent from. A Bubble app that declares unlisted does not get a longer call—Bubble still cuts the connection, and the extra time is spent on an answer nobody receives.

If you use the Bubble plugin, it sets this field for you—there is nothing to configure.

reset_session

Controls whether the agent remembers the exchanges leading up to this message.

• yes — This is a new session. Clear the message history and start fresh.
• no — Continue the current session. Preserve the message history so the agent keeps its context.

extra_context

An optional object containing extra information you'd like the agent to take into account when responding. Use it to pass details your agent cannot infer from the prompt alone—for example:

• The caller's name — e.g. "John Smith"
• The caller's location — e.g. "Boulder, Colorado"

Anything you include here becomes context the agent can use to tailor its answer, so it can greet the caller by name or give location-aware responses.

Response Body

A successful call comes back as 200 OK with a JSON body holding the agent's reply:

200 OK
{
  "agent_response": "This text will contain the response from your agent"
}

Field	Type	Description
agent_response	string	The agent's reply to client_prompt.

The session history itself is kept for you. Send the same session_id again with reset_session: "no" and the agent picks up where it left off, so there's nothing to store and replay on your side.

Errors

Errors come back in one of two body shapes, depending on how far into the gateway the request got. The status code tells the two shapes apart.

Requests that make it past the edge come back as JSON with an error string:

Error body
{
  "error": "Insufficient credits"
}

Requests rejected at the edge come back as RFC 9457 application/problem+json instead.

Problem body
{
  "type": "https://httpproblems.com/http-status/401",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Authorization Failed",
  "instance": "/v1/response-agent",
  "trace": { "timestamp": "...", "requestId": "..." }
}

Status	Body	Meaning
400	problem+json	The request body is malformed—a missing or misspelled field, or an agent_id that is not in pa-000000 form.
401	problem+json	The Authorization header is missing or the key is not valid.
429	problem+json	You have gone over your requests-per-minute limit. See Rate Limits.
402	error	You are out of credits. Top up on the Credits page—see Pricing.
4xx	error	Your agent rejected the request. The error string is the agent's own explanation.
500	error	Something failed on our side. Nothing is charged for a 500.

A 402 carries an extra "code": "INSUFFICIENT_CREDITS" field so you can branch on it without matching the message text, and a 429 carries a Retry-After header.

Long-running requests

Most calls answer in a few seconds and behave exactly as the table above describes. A call that runs longer—around 20 seconds or more—switches to a different delivery mode automatically. You do not request it and you cannot turn it off.

In that mode we start the response before your agent has finished.
We do this so the API connection stays open and intermediaries do not disconnect it. Two things follow.

The status code is sent early, so it is always 200. It is committed before the outcome is known, and it cannot be changed afterwards. A failure on a long-running call therefore arrives as 200 OK with an error body:

200 OK — but an error
{
  "error": "Internal Server Error"
}

So treat the presence of an error key as the error signal, and read agent_response only when error is absent. This is the safe rule for short calls as well, which is why the caution above states it for every response.

The different delivery mode mentioned above does not make an API call run longer; it only keeps the API connection open while your agent works.