Genie runs
Run 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.
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 was accepted. Poll Get a Genie run with conversation_id and region until status leaves processing.
application/json- response
The handle of a run started in the background.
status*"processing"Always processing: the Genie has not answered yet.
"processing"conversation_id*stringThe conversation of the run: poll it with Get a Genie run, and send it back to continue the conversation.
uuidregion*stringData region the conversation is stored in. Pass it as region when polling.
"besg""usnv"message_id*nullAlways null: no reply yet.
curl -X POST 'https://genies.stacksync.com/v1/workspaces/0/genies/run' \ -H 'Content-Type: application/json' \ -d '{ "input": "Who are you?", "region": "usnv"}'{ "status": "processing", "conversation_id": "14d0a0ba-9352-44d6-a7f7-8fd2c3ce0388", "region": "usnv", "message_id": null}GETGet a Genie run
Returns the state of a run started with Run a Genie and, once the Genie has answered, its latest reply. Pass the region the run answer carried: the conversation is read from that data region. While the Genie works, status is processing and there is no result; completed carries the reply in result and its id in message_id; failed means the run could not finish.
POSTRun 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.