---
title: "Create an action"
method: POST
path: "/actions"
---

# Create an action

`POST /actions`

Create a new action that the AI agent can call during conversations. The payload field uses OpenAPI-style parameter and request body specifications to define how the API call should be constructed.

## Request body

- CreateActionPublicDto
  - `name` string, required — Action display name
  - `description` string — What this action does
  - `api_endpoint` string, uri, required — The full API endpoint URL to call
  - `request_type` 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE', required — HTTP method
  - `operation_id` string — Unique operation ID (auto-generated from name if omitted)
  - `payload` object, required — OpenAPI-style operation spec: parameters, requestBody, responses, etc.
    - `base_url` string — Base URL for the API endpoint
    - `path` string — API path (e.g. "/api/v1/bookings")
    - `method` string — HTTP method (get, post, put, delete, patch)
    - `operationId` string — OpenAPI operation ID
    - `summary` string
    - `description` string
    - `parameters` object[] — Request parameters
      - `name` string, required — Parameter name
      - `in` 'query' | 'path' | 'header' | 'cookie', required — Where the parameter is sent
      - `description` string
      - `required` boolean
      - `schema` object — JSON Schema for the parameter value
    - `requestBody` object — Request body specification
      - `description` string
      - `required` boolean
      - `content` object, required — Content type to schema mapping (e.g. "application/json": { schema: {...} })
    - `responses` object — Response specifications keyed by status code
  - `enabled_on_channel` object — Channel restrictions (defaults to web only)
    - `channels` SessionChannel[], required — Channels where this action is available (e.g. ["web", "email", "whatsapp"])
  - `pinned` boolean — Whether to pin this action prominently
  - `tags` string[] — Tags for organizing actions
  - `require_form_submission` boolean — Require the user to submit a form before executing
  - `restricted_to_segments` string[] — Contact segment ids this action is restricted to. Empty/omit = available to all contacts. Segment ids come from list contact segments.

## Response `201`

Default Response

- ActionPublicResponseDto
  - `id` string, required — Unique action ID
  - `name` string, required — Action display name
  - `description` string, nullable, required — What this action does
  - `api_endpoint` string, nullable, required — The API endpoint URL this action calls
  - `request_type` string, nullable, required — HTTP method (GET, POST, PUT, PATCH, DELETE)
  - `operation_id` string, nullable, required — Unique operation ID used to reference this action
  - `payload` object, nullable, required — OpenAPI-style operation specification for the action
    - `base_url` string — Base URL for the API endpoint
    - `path` string — API path (e.g. "/api/v1/bookings")
    - `method` string — HTTP method (get, post, put, delete, patch)
    - `operationId` string — OpenAPI operation ID
    - `summary` string
    - `description` string
    - `parameters` object[] — Request parameters
      - `name` string, required — Parameter name
      - `in` 'query' | 'path' | 'header' | 'cookie', required — Where the parameter is sent
      - `description` string
      - `required` boolean
      - `schema` object — JSON Schema for the parameter value
    - `requestBody` object — Request body specification
      - `description` string
      - `required` boolean
      - `content` object, required — Content type to schema mapping (e.g. "application/json": { schema: {...} })
    - `responses` object — Response specifications keyed by status code
  - `status` string, nullable, required — Action status (e.g. "live")
  - `pinned` boolean, required — Whether this action is pinned prominently
  - `tags` string[], required — Tags for organizing actions
  - `enabled_on_channel` object, required — Channel restrictions
    - `channels` SessionChannel[], required — Channels where this action is available
  - `is_handoff_like` boolean, required — Whether this action behaves like a handoff to a human agent
  - `require_form_submission` boolean, nullable, required — Whether a form must be submitted before the action executes
  - `restricted_to_segments` string[], required — Contact segment ids this action is restricted to. Empty = available to all contacts.
  - `created_at` string, date-time, required — When the action was created
  - `updated_at` string, date-time, required — When the action was last updated

## Other responses

- `500` — Internal Server Error

---

[API](https://skmtc.net/open/apis/opencx-api.md) · [All operations](https://skmtc.net/open/apis/opencx-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/open/opencx-api/versions/57b06b52302d/schema)