---
title: "Create Actions"
method: POST
path: "/actions/create"
tags: ["Actions"]
---

# Create Actions

`POST /actions/create`

## Request

- Base URL: `https://api.peec.ai/customer/v1`
- URL: `https://api.peec.ai/customer/v1/actions/create`
- Auth: one of:
  - API key in header `X-API-Key`
  - API key in query parameter `api_key`
  - HTTP bearer

Record work the customer decided to do themselves as actions, in the same shape as the ones Peec generates, so they sort, filter and move through the same statuses. The kind picked decides an action's type and group. The linked topic and prompts are resolved against the project, and an item naming one it does not hold lands in `rejected` on its own — the batch never fails as a whole.

## Request body

- object
  - `project_id` string: Required if using a company api key
  - `actions` object[], required: Up to 50 actions to write.
    - `description` object: What the action is for. `html` is the formatting the app's editor renders; `text` is what everything else reads.
      - `text` string, required
      - `html` string
    - `notes` object, nullable: Working notes kept beside the action. Null clears them.
      - `text` string, required
      - `html` string
    - `topic_id` string, nullable: Topic the action is scoped to, from the topics endpoint. Null clears it.
    - `prompt_ids` string[]: Prompts this action is meant to move, from the prompts endpoint. Replaces the whole list.
    - `steps` object[]: The work to do, replacing the whole step list.
      - `title` string, required: What to do, as one line.
      - `description` string: Detail below the step's own line.
      - `completed` boolean
      - `section` string: Heading this step sits under. Steps naming the same one are grouped together, in the order they first appear; steps naming none sit in the default list above every group.
    - `priority` 'none' | 'low' | 'medium' | 'high': How much the action matters. It fills the same impact bars a generated action fills from its predicted lift, which is what lets the two sort together.
    - `country_codes` string[], nullable: ISO 3166-1 alpha-2 markets the action is scoped to. Null means every market the project tracks.
    - `language_codes` string[], nullable
    - `tag_ids` string[]
    - `category` string, nullable
    - `assignee_user_id` string, nullable: The project member who owns the work. Null unassigns it.
    - `due_on` string, date, nullable: Calendar day in the project's timezone. Null clears it.
    - `repeat` object, nullable: How often the work comes round again. Completing an action you wrote opens its next round as a new `PENDING` action, due one interval after this one (or after the day it was completed, when no `due_on` is set), and this one stops repeating. Null makes it one-off.
      - `every` integer, required
      - `unit` 'day' | 'week' | 'month' | 'year', required
    - `time_range` '7d' | '28d' | '90d' | 'all', nullable: The window the action's own measurements are read over.
    - `title` string, required
    - `kind` 'CONTENT_OPTIMIZATION' | 'CONTENT_CREATION' | 'MENTION' | 'TECHNICAL' | 'PRODUCT_PAGE' | 'OTHER', required: What the work is, which decides the action's type and group so it files beside the generated ones: `CONTENT_OPTIMIZATION` (Content optimization), `CONTENT_CREATION` (Create content), `MENTION` (Improve a mention), `TECHNICAL` (Fix a technical issue), `PRODUCT_PAGE` (Improve a product page), `OTHER` (Something else).
    - `status` 'PENDING' | 'PLANNED' | 'ACCEPTED' | 'REJECTED' | 'COMPLETED': Where the action starts. Defaults to `PLANNED`, to do and not started; `ACCEPTED` is in progress, `COMPLETED` is done, `REJECTED` was declined. `PENDING` is accepted and lands as `PLANNED`.
    - `completed_at` string, date-time: When the work was done, as an ISO 8601 date-time with an offset. Only a `COMPLETED` action takes one; it may be up to five years back and never in the future. Omitted means now. It is the date the action marks on the impact chart.
    - `page_url` string: The page the action lands on. Empty means it names no page. On an owned-page kind this is also the page the action is measured against.

## Response `200`

Per-item results, `index` naming the position in the request.

- object: Per-item results, `index` naming the position in the request.
  - `created` object[], required
    - `index` number, required
    - `action_id` string, required
    - `title` string, required
  - `rejected` object[], required
    - `index` number, required
    - `reason` 'invalid', required
    - `message` string, required

## Changes

- **2026-11-03** `9fdffdff48a5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/peec/apis/peec-ai-customer-api/changes/actions/create/post.md)

---

[API](https://skmtc.dev/peec/apis/peec-ai-customer-api.md) - [All operations](https://skmtc.dev/peec/apis/peec-ai-customer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/peec/apis/peec-ai-customer-api/revisions/9d774600c8eb?raw)