/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
API Reference Run an API Request

Run an API Request

Send a request a reader confirmed in an agent mode run card, with their own key, and return the response.

POST/v1/projects/{projectId}/chat/runTry it
Session token

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.

Warning

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

NameDescription
projectId:stringpathRequired
The project ID (a UUID). Anything else gets 404.

Request Body

NameDescription
visitorId:stringbodyRequired
The anonymous visitor identifier (1–100 chars). Used for the per-visitor limit.
method:stringbodyRequired
GET, POST, PUT, PATCH or DELETE.
url:stringbodyRequired
The full URL, up to 2048 characters. It must use a server from the project's endpoint catalog (same origin and path prefix) and a documented path for this method. URLs with userinfo, or with encoded ., / or \ (%2e, %2f, %5c), are refused.
headers:objectbody
Request headers as name–value strings: at most 20, each value up to 4096 characters. Include the reader's key here when your API takes it in a header. Host, Cookie, Connection, Transfer-Encoding and other hop-by-hop headers are dropped.
Default{}
body:stringbody
The request body, up to 100,000 characters.
confirmed:booleanbody
The reader pressed Run request. Required as true for POST, PUT, PATCH and DELETE.
typed:stringbody
DELETE only: the method name as the reader typed it. Must be exactly DELETE.

What is sent, and where

•
Only for a project that turned on agent.runRequests and has an endpoint catalog (built from its OpenAPI spec when you publish).
•
Only to a server, path and method in that catalog, and only for an endpoint whose page the reader's audience can see. - Only to public addresses: private and local addresses are refused, including names that resolve to them.
•
Redirects are not followed: a 3xx comes back as the result.
•
The request times out after 10 seconds, and the response body is cut at 512 KB (marked [Response truncated at 512KB]).

Response

200 with Cache-Control: private, no-store, whatever status your API answered:

NameDescription
data.status:integer
Your API's status code. 0 when no response came back (for example a timeout; statusText is then Request Timeout or Network Error).
data.headers:object
Your API's response headers, without set-cookie.
data.body:string
The response body as text.
data.sandbox:boolean
true when the server is marked x-syntext-sandbox: true; false means the live API.

Error Responses

StatusCodeWhen
403FORBIDDENThe request didn't come through the doc site
400CONFIRMATION_REQUIREDA POST, PUT, PATCH or DELETE without confirmed: true, or a DELETE without typed: "DELETE"
429RATE_LIMITEDOver a run limit, or too many runs in flight for the project or organization. Has a Retry-After header and retryAfterSeconds
404NOT_FOUNDThe project doesn't exist or was deleted
409RUNS_DISABLEDThe project hasn't turned on agent.runRequests
403NOT_ALLOWEDThe URL, path or method isn't in the endpoint catalog, or the endpoint's page is hidden from the reader
403BLOCKED_HOSTThe host is, or resolves to, a private or local address
400validation_errorThe 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.

json
{
"error": {
"code": "RATE_LIMITED",
"message": "Too many requests. Please try again later.",
"retryAfterSeconds": 420
}
}
Was this page helpful? Yes No
Request
cURLJavaScriptPythonGoRubyPHPJavaC#cURL
curl --request POST \
--url 'https://api.syntext.dev/v1/projects/{projectId}/chat/run' \
--header 'Authorization: Bearer <jwt>' \
--header 'Content-Type: application/json' \
--data '{
"visitorId": "string",
"method": "string",
"url": "string",
"headers": {},
"body": "string",
"confirmed": true,
"typed": "string"
}'
Responseapplication/json
json
{
"data": {
"status": 201,
"statusText": "Created",
"headers": { "content-type": "application/json" },
"body": "{\"id\":\"dom_123\",\"hostname\":\"docs.acme.dev\"}",
"timeMs": 182,
"sandbox": true
}
}
Product
Resources
Company
© 2026 SyntextBuilt with Syntext