Run an API Request
Send a request a reader confirmed in an agent mode run card, with their own key, and return the response.
Sends a request that a doc-site reader confirmed in a run card on the /ask page, with the key they pasted there, and returns your API's response. The assistant only proposes requests (the run event); this route is what sends one. See Running API requests from answers.
Reached only through your doc site. Readers run requests from the assistant on your doc site; any direct call to the API gets 403 FORBIDDEN before anything else is checked.
The reader's key travels in headers (or in the URL's query, when your API takes it there). It passes through Syntext to your API for this request only: it's never stored, never logged and never given to the assistant. No playground history is written.
Path Parameters
projectId404.Request Body
visitorIdmethodGET, POST, PUT, PATCH or DELETE.url., / or \ (%2e, %2f, %5c), are refused.headersHost, Cookie, Connection, Transfer-Encoding and other hop-by-hop headers are dropped.{}bodyconfirmedtrue for POST, PUT, PATCH and DELETE.typedDELETE only: the method name as the reader typed it. Must be exactly DELETE.What is sent, and where
agent.runRequests and has an endpoint catalog (built from its OpenAPI spec when you publish).3xx comes back as the result.[Response truncated at 512KB]).Response
200 with Cache-Control: private, no-store, whatever status your API answered:
data.status0 when no response came back (for example a timeout; statusText is then Request Timeout or Network Error).data.headersset-cookie.data.bodydata.sandboxtrue when the server is marked x-syntext-sandbox: true; false means the live API.Error Responses
| Status | Code | When |
|---|---|---|
| 403 | FORBIDDEN | The request didn't come through the doc site |
| 400 | CONFIRMATION_REQUIRED | A POST, PUT, PATCH or DELETE without confirmed: true, or a DELETE without typed: "DELETE" |
| 429 | RATE_LIMITED | Over a run limit, or too many runs in flight for the project or organization. Has a Retry-After header and retryAfterSeconds |
| 404 | NOT_FOUND | The project doesn't exist or was deleted |
| 409 | RUNS_DISABLED | The project hasn't turned on agent.runRequests |
| 403 | NOT_ALLOWED | The URL, path or method isn't in the endpoint catalog, or the endpoint's page is hidden from the reader |
| 403 | BLOCKED_HOST | The host is, or resolves to, a private or local address |
| 400 | validation_error | The body failed validation |
Body validation comes first; then the checks run in this order: doc-site origin, confirmation, the visitor, IP and project limits, the project and its switch, the organization limit, then the catalog.