---
title: "Create a chat command"
method: POST
path: "/api/v3/workspaces/{workspace}/chat-config/commands"
tags: ["Commands"]
---

# Create a chat command

`POST /api/v3/workspaces/{workspace}/chat-config/commands`

Create a slash-command. Set cron_schedule to run the command on a schedule and deliver artifacts to sink_configs.

## Path parameters

- `workspace` string, required

## Request body

- CommandCreate
  - `name` string, required
  - `command_content` string, required — The prompt the assistant runs
  - `scope_type` 'workspace' | 'persona' | 'user', required
  - `scope_id` string, nullable — Required for persona scope (persona short name)
  - `description` string
  - `is_active` boolean
  - `cron_schedule` string — Cron expression to schedule the command (optional)
  - `sink_configs` object[] — Delivery sinks for scheduled artifacts (optional)
  - `assistant_name` string — Assistant persona for scheduled fires (optional)
  - `run_as_user` string — User identity scheduled fires run as (optional)
  - `max_runs` integer — Cap on total scheduled runs (optional)
  - `auto_approve_readonly` boolean — Auto-approve read-only tasks on scheduled fires (optional)

## Response `201`

Command created

- Command — A chat command (slash-command). Commands package a repeatable investigation procedure that an assistant runs on demand or on a schedule.
  - `id` integer
  - `name` string
  - `command_content` string — The prompt the assistant runs
  - `description` string, nullable
  - `scope_type` 'workspace' | 'persona' | 'user'
  - `scope_id` string, nullable
  - `workspace_name` string
  - `is_active` boolean
  - `cron_schedule` string, nullable — Cron expression for scheduled runs (optional)
  - `sink_configs` object[] — Delivery sinks for scheduled command artifacts (e.g. Slack)
  - `assistant_name` string, nullable — Assistant persona that runs scheduled fires
  - `created_at` string, date-time
  - `updated_at` string, date-time

## Other responses

- `403` — Workspace admin required for workspace/persona scope

---

[API](https://skmtc.dev/runwhen/apis/runwhen-platform-api.md) · [All operations](https://skmtc.dev/runwhen/apis/runwhen-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/runwhen/runwhen-platform-api/revisions/9d1a64d4b1c1/schema)