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

Source: https://docs.stacksync.com/api-reference/genies/runs/run_genie

`POST https://genies.stacksync.com/v1/workspaces/{workspace_id}/genies/run`

- Operation: `run_genie`
- Resource: Genie runs
- Access: writes data

## Authentication

- `Authorization: Bearer <key>`: A workspace API key (workspace_…, created by a workspace owner under Workspace settings > Stacksync API) acts with editor rights on that workspace only; a user API key (user_…, created under Profile > Stacksync API) acts as that user in every workspace they belong to. POST requests must send Content-Type: application/json. Every authentication failure answers 403. Running a Genie needs the editor role in the workspace.
- `Content-Type: application/json` on every request with a body.

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `workspace_id` | integer | Yes | 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. |

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `genie_id` | string | No | The 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` | string (besg \| usnv) | No | Data 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. |

## Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | string \| object | Yes | 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` | string (uuid) | No | The 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. |
| `region` | string (besg \| usnv) | No | Data region of the Genie, where the conversation is stored. Allowed values: besg, usnv. Same meaning as the region query parameter; this value wins. |
| `options` | object (RunGenieOptions) | No | Options of the run. |
| `options.dispatch_external_message` | object (ApprovalDispatch) | No | Where an approval request is delivered when the Genie pauses on an action that needs one. Both interface_type and interface_id are needed; the destination inside that interface (a channel, an address) is taken from the Genie's master prompt. Without it the approval is only returned in options.approval of the reply. |
| `options.dispatch_external_message.interface_type` | string (slack \| teams \| email) | Yes | The type of the Genie's configured interface that delivers the approval request. Allowed values: slack, teams, email. |
| `options.dispatch_external_message.interface_id` | string | Yes | The id of that configured interface of the Genie. |
| `options.dispatch_external_message.attachement_file_ids` | array of string | No | Ids of stored files to deliver with the approval request. The files must belong to this request or conversation. |
| `source` | string | No | A 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` | boolean, default false | No | true runs only the checks of the run (the Genie exists and is active) and answers 204 without asking the Genie or storing anything. |

## Returns

### 202 The run was accepted. Poll Get a Genie run with conversation_id and region until status leaves processing.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string (processing) | Yes | Always processing: the Genie has not answered yet. |
| `conversation_id` | string (uuid) | Yes | The conversation of the run: poll it with Get a Genie run, and send it back to continue the conversation. |
| `region` | string (besg \| usnv) | Yes | Data region the conversation is stored in. Pass it as region when polling. |
| `message_id` | null | Yes | Always null: no reply yet. |

### 204 validate_only was true and every check of the run passed (the Genie, the conversation). Nothing was asked and nothing was stored.

No body.

## Example request

```bash
curl -X POST "https://genies.stacksync.com/v1/workspaces/{workspace_id}/genies/run" \
  -H "Authorization: Bearer $STACKSYNC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input": "Who are you?",
  "region": "usnv"
}'
```

## Example response (202)

```json
{
  "status": "processing",
  "conversation_id": "14d0a0ba-9352-44d6-a7f7-8fd2c3ce0388",
  "region": "usnv",
  "message_id": null
}
```

## Errors

| Status | Meaning | Body |
| --- | --- | --- |
| 400 | The request could not be read: the body is not a JSON object, input is missing, source is a reserved value, validate_only is not true or false, or workspace_id is not a number. | `{ "error": string, "msg": string, "field": string }` |
| 403 | The caller is not allowed: Authorization Error (header missing or not Bearer), Invalid API Key (unknown key, key of another workspace, or a user who is not a member of the workspace), Content-Type Error (POST without application/json), Insufficient Scope (a read-only sign-in on a request that changes data) or Authentication Error (your role in the workspace is below editor). | `{ "error": string, "msg": string, "field": string }` |
| 404 | genie_id names no Genie in this region. | `{ "error": string (genie_not_found \| genie_inactive), "message": string }` |
| 409 | genie_id names a Genie that is switched off. Switch it on before asking it. | `{ "error": string (genie_not_found \| genie_inactive), "message": string }` |

## Related

- [API Reference overview](https://docs.stacksync.com/api-reference): base URLs, regions, pagination, idempotency and errors
- [Authentication](https://docs.stacksync.com/api-reference/authentication): API keys and the 403 answers
- OpenAPI document: https://docs.stacksync.com/openapi-genies.json
- [Get a Genie run](https://docs.stacksync.com/api-reference/genies/runs/get_genie_run)
- [Run a Genie and wait for the result](https://docs.stacksync.com/api-reference/genies/runs/run_genie_and_wait)