Genie runs
Run a Genie and wait for the result
Sends a message to a Genie and answers once the Genie has finished with it, so the reply is in the same response. A Genie that calls several tools can take minutes; keep the connection open or use Run a Genie and poll instead. Omit genie_id to let the workspace's Genie dispatcher pick the Genie; pass conversation_id to continue an earlier conversation. The answer has the same shape as Get a Genie run.
Authorization
AuthorizationstringheaderrequiredBearer <key>, where <key> is a workspace API key or a user API key. See Authentication.
workspace_id*integerThe workspace whose Genie runs. A workspace API key works only on its own workspace; a user API key on any workspace the user belongs to.
genie_id?stringThe Genie to run (its id from the Genies list). Omitted, the workspace's Genie dispatcher selects the Genie that best fits the message; a follow-up without genie_id goes through the dispatcher again and may reach another Genie. A named Genie must exist in the region and be active.
region?stringData region of the resources: the region of the Genie, where the conversation is stored. Allowed values: besg, usnv. Defaults to the region of the server that answers, so always pass the Genie's region. A value in the request body wins over the query parameter.
"besg""usnv"application/json- body
The message for a Genie and how to run it. genie_id and region may also be sent here instead of the query string; a body value wins.
input*|The message handed to the Genie. A string is used as is; a JSON object is encoded as text so nothing is lost.
conversation_id?stringThe conversation to continue, from an earlier run answer: the earlier messages are the Genie's context, and a failed conversation reopens. Omitted, a new conversation starts.
uuidregion?stringData region of the Genie, where the conversation is stored. Allowed values: besg, usnv. Same meaning as the region query parameter; this value wins.
"besg""usnv"options?Options of the run.
source?stringA label of your own for where the message came from, stored on it. Omitted or blank, api. The values slack, email, teams and public_api are reserved and refused.
validate_only?booleantrue runs only the checks of the run (the Genie exists and is active) and answers 204 without asking the Genie or storing anything.
falseThe run finished, or could not: status says which. completed carries the reply in result; failed carries the reason in error when the run stopped before the Genie answered; processing means the message steered a run that is still going, so poll Get a Genie run.
application/json- response
The state of a run and, once the Genie answered, its latest reply.
status*stringprocessing: the Genie is still working (or the message steered a run in progress). completed: the Genie answered; result holds the reply. failed: the run could not finish.
"processing""completed""failed"conversation_id*|The conversation of the run. Send it back to continue the conversation.
uuidregion*|Data region the conversation is stored in. Null only on a failure answered before the region was resolved.
"besg""usnv"nullmessage_id*|Id of the Genie's latest reply in the conversation; null while there is none.
uuidresult?stringThe text of the Genie's latest reply. Present once the conversation holds a reply.
widget?The structured action the reply proposes, when the Genie attached one to its reply.
options?Details attached to the reply. Carries approval when the Genie paused on an action that needs an approval; decide it with the approval decision operation using the same API key.
attachments?array<>The files the reply produced, as stored file references. Present once the conversation holds a reply; empty when the reply has no file.
error?stringWhy the run failed, when it stopped before the Genie answered or the region is unknown.
curl -X POST 'https://genies.stacksync.com/v1/workspaces/0/genies/run_wait_result' \ -H 'Content-Type: application/json' \ -d '{ "input": "Repeat the first thing I said to you.", "conversation_id": "d10c810f-1187-4a6e-9df9-ac2e87d02f2d", "region": "usnv"}'{ "status": "completed", "conversation_id": "d10c810f-1187-4a6e-9df9-ac2e87d02f2d", "region": "usnv", "message_id": "aef1f941-d148-4833-9118-86f59c358d5a", "result": "Hello, world! I am the Hello World API Demo genie.", "attachments": [], "options": {}}POSTRun a Genie
Starts a Genie run in the background and answers at once with the conversation to poll. Send the Genie's reply back with Get a Genie run, passing the region this answer carries. Omit genie_id to let the workspace's Genie dispatcher pick the Genie that fits the message; pass conversation_id to continue an earlier conversation. A message sent while the conversation is still processing is handed to the running Genie as steering instead of starting a new run.
GETList API proxies
The API proxies of the workspace in one region that the caller may see (created by them, or shared), newest first.