See Stacksync in action with a solution architect. Book a demo ↗
StacksyncDocs
StacksyncCommunityBook a demoContact Support
HomeTwo-way syncAgentic WorkflowsGeniesEnterprise OSMCPEDIConnectorsSecurity and Other ResourcesChangelogDevelopersAPI Reference
GeniesRuns

Genie runs

Get a Genie run

GET
/v1/workspaces/{workspace_id}/genies/run/{conversation_id}

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.

Authorization

Authorizationstringheaderrequired

Bearer <key>, where <key> is a workspace API key or a user API key. See Authentication.

Path Parameters

workspace_id*integer

The 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.

conversation_id*string

The conversation_id the run answer carried.

Formatuuid

Query Parameters

region?string

Data region of the resources: the region the run answer carried. Allowed values: besg, usnv. Defaults to the region of the server that answers, so always pass it.

Value in"besg""usnv"

Response Body

The run's current state. A conversation not yet stored answers processing.

application/json
  1. response

The state of a run and, once the Genie answered, its latest reply.

status*string

processing: 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.

Value in"processing""completed""failed"
conversation_id*|

The conversation of the run. Send it back to continue the conversation.

Formatuuid
region*|

Data region the conversation is stored in. Null only on a failure answered before the region was resolved.

Value in"besg""usnv"null
message_id*|

Id of the Genie's latest reply in the conversation; null while there is none.

Formatuuid
result?string

The 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?string

Why the run failed, when it stopped before the Genie answered or the region is unknown.

Get a Genie run
curl -X GET 'https://genies.stacksync.com/v1/workspaces/0/genies/run/497f6eca-6276-4993-bfeb-53cbbbba6f08?region=usnv'
{  "status": "completed",  "conversation_id": "14d0a0ba-9352-44d6-a7f7-8fd2c3ce0388",  "region": "usnv",  "message_id": "346f36a0-1902-4871-87d1-11f2d5433d9b",  "result": "Hello, world! I am the Hello World API Demo genie.",  "attachments": [],  "options": {}}

GETGet a Genie browser session

A browser session a Genie opened in a conversation: its status and, while live, its live view.

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.