---
title: "Create a genie"
method: POST
path: "/v1/workspaces/{workspace_id}/genies"
tags: ["Genies"]
---

# Create a genie

`POST /v1/workspaces/{workspace_id}/genies`

## Request

- Base URL: `https://api.stacksync.com`
- URL: `https://api.stacksync.com/v1/workspaces/{workspace_id}/genies`
- Auth: HTTP bearer

The configuration's defaults are the web app's (every tool on); the description is written by Stacksync from the instructions. Send a configuration made by the genies setup wizard (genies.stacksync.com .../genies/wizard/generate-config) after filling the connection of each skill.

## Path parameters

- `workspace_id` integer, required

## Query parameters

- `region` 'besg' | 'usnv', required

## Headers

- `Idempotency-Key` string, nullable: Makes the create retry-safe for 24 hours: a retry with the same key answers the resource the first call created, with the Idempotent-Replayed: true header, and creates nothing. 1 to 255 visible ASCII characters. The same key with a different request answers 422; while the first call still runs, 409.

## Request body

- CreateGenieBody
  - `name` string, required: Unique among the workspace's genies of the region
  - `folder_id` string, uuid, nullable: The folder to create it in; the root when absent
  - `is_shared_with_workspace` boolean: Whether every member of the workspace sees it
  - `genie_config` GenieConfigInput
    - `master_prompt` string: The genie's instructions
    - `description` string: Leave empty: Stacksync writes it from the instructions
    - `model` string: The LLM the genie runs on; empty for Stacksync's default
    - `interfaces` GenieInterfaceDocument[]
      - `id` string, required
      - `type` string, required: slack, teams or email
      - `details` string, required: For email: the address '<alias>@stacksync.email'
      - `connection_id` string: The Slack or Teams connection of the workspace; empty for email
      - `connection_resource_id` string: The resource id of that connection; empty for email
    - `skills` GenieSkillDocument[]
      - `id` string, required: The module id
      - `name` string, required
      - `description` string
      - `type` 'Module'
      - `enabled` boolean
      - `connection` string, nullable: The connection id the action runs with
      - `connection_resource_id` string, nullable: The resource id of that connection
      - `approval_policy` 'always_allow' | 'approval_required': approval_required pauses the genie until a person approves the action
    - `app_descriptions` object: Per skill app type: when and how the genie uses that app
    - `resources` GenieResourceDocument[]
      - `name` string, required
      - `type` 'connection' | 'variable' | 'secret', required
      - `value` string, required: The connection id or the variable id
      - `instructions` string
    - `teams` GenieTeamDocument[]
      - `id` string, required
      - `name` string, required
    - `contacts` GenieContactDocument[]
      - `id` string, required
      - `name` string, required
      - `email` string, required
    - `tools` GenieToolsDocument: The built-in tools the genie may use; all on by default, as in the web app
      - `web_search` boolean
      - `execute_browser` boolean
      - `api_call` boolean
      - `code_execution` boolean
      - `stacksync_ocr` boolean
      - `modify_scheduled_task` boolean
    - `api_key` string, nullable: Your own LLM API key for the model; never returned
  - `knowledge_bases` GenieKnowledgeBaseDocument[]
    - `knowledge_base_id` string, uuid, required: As answered by the knowledge base routes
    - `instructions` string
  - `validate_only` boolean: Run every check of the write and answer 204 without writing: a refused write answers the error the write would

## Response `201`

Created

- CreatedGenie
  - `genie_id` string, required
  - `name` string, required
  - `region` 'besg' | 'usnv', required
  - `folder_id` string, nullable
  - `status` string, nullable
  - `public_access_rights` string, nullable
  - `is_shared_with_workspace` boolean, nullable
  - `has_api_key` boolean, required: Whether an LLM API key of yours is stored (the key itself is never returned)
  - `genie_config` GenieConfigDocument, required: What the genie does and how: its instructions, channels, skills, resources and tools
    - `master_prompt` string: The genie's instructions
    - `description` string: Leave empty: Stacksync writes it from the instructions
    - `model` string: The LLM the genie runs on; empty for Stacksync's default
    - `interfaces` GenieInterfaceDocument[]
      - `id` string, required
      - `type` string, required: slack, teams or email
      - `details` string, required: For email: the address '<alias>@stacksync.email'
      - `connection_id` string: The Slack or Teams connection of the workspace; empty for email
      - `connection_resource_id` string: The resource id of that connection; empty for email
    - `skills` GenieSkillDocument[]
      - `id` string, required: The module id
      - `name` string, required
      - `description` string
      - `type` 'Module'
      - `enabled` boolean
      - `connection` string, nullable: The connection id the action runs with
      - `connection_resource_id` string, nullable: The resource id of that connection
      - `approval_policy` 'always_allow' | 'approval_required': approval_required pauses the genie until a person approves the action
    - `app_descriptions` object: Per skill app type: when and how the genie uses that app
    - `resources` GenieResourceDocument[]
      - `name` string, required
      - `type` 'connection' | 'variable' | 'secret', required
      - `value` string, required: The connection id or the variable id
      - `instructions` string
    - `teams` GenieTeamDocument[]
      - `id` string, required
      - `name` string, required
    - `contacts` GenieContactDocument[]
      - `id` string, required
      - `name` string, required
      - `email` string, required
    - `tools` GenieToolsDocument: The built-in tools the genie may use; all on by default, as in the web app
      - `web_search` boolean
      - `execute_browser` boolean
      - `api_call` boolean
      - `code_execution` boolean
      - `stacksync_ocr` boolean
      - `modify_scheduled_task` boolean
  - `knowledge_bases` GenieKnowledgeBaseDocument[], required
    - `knowledge_base_id` string, uuid, required: As answered by the knowledge base routes
    - `instructions` string
  - `created_time` string, date-time, nullable
  - `last_modified_time` string, date-time, nullable

## Other responses

- `204`: No Content
- `400`: Bad Request
- `403`: Forbidden
- `409`: Conflict
- `422`: Unprocessable Content

---

[API](https://skmtc.dev/stacksync/apis/stacksync-api.md) - [All operations](https://skmtc.dev/stacksync/apis/stacksync-api/llms.txt) - [OpenAPI document](https://skmtc.dev/stacksync/apis/stacksync-api/revisions/21f4ba4b214e?raw)