Send a prompt to a project (project API key)
Queues a prompt exactly as if the key’s creator typed it in the app. Needs a PROJECT key (Project settings → API), which only works on its own project. Returns at once with the prompt’s id; poll its URL for the reply. Prompts from one key continue one conversation unless freshSession is true. Paid tools cannot be run this way.
A run may pause to ask a question (status paused_for_question); it then holds the project’s queue until it is answered with the prompt’s /answer call or cancelled. An unattended caller should send questions: "never", which tells the run to state its assumptions and carry on instead of asking. callbackUrl is POSTed the prompt’s view (plus event) when it pauses or finishes, so there is no need to poll; the callback carries no secret, so confirm anything that matters with a GET on the prompt.
Authentication
Create one in the app under Settings → API keys. It is shown once and stored only as a hash, so it cannot be recovered — losing it means issuing a new one.
A key reads the endpoints below and nothing else. It is not a session: it cannot create or delete projects, change settings, or issue another API key. It sees exactly what its owner sees, re-checked on every request, so removing someone’s access to a project removes it from their key on the very next call.
The same key, sent as Authorization: Bearer <key>.
Path parameters
Request
Public https URL to POST when the prompt pauses on a question or finishes (events: paused_for_question, completed, error, cancelled).
never: the run must not ask; it states assumptions instead.
Response
Present while status is paused_for_question.
Returned on POST: where to poll.