PEpeec
Actions

List Actions

Changed on

The project's actions, the ones Peec generated and the ones the customer wrote themselves alike: what to do, on which page or site, and how much impact it is expected to have if it is done. created_by says which of the two an action is, and only a customer's own can be deleted or reshaped. Filters combine with AND, except targets, groups, archetypes and platforms, which combine with OR across the four. The action detail endpoint carries a single action's steps, brief, evidence and impacted prompts.

post/actions/list

Request

  • Base URL
    https://api.peec.ai/customer/v1
  • URL
    https://api.peec.ai/customer/v1/actions/list
  • Auth
    • API key in header X-API-Key
    • or API key in query parameter api_key
    • or HTTP bearer

Request body

project_idstring

Required if using a company api key

typesstring[]

Defaults to every published type. TEMPLATE_ACTION is a per-platform playbook filled in for one page; CONTENT_BRIEF and CATEGORY_SITUATION_BRIEF are net-new content to write; CONTRADICTIONS_EXTERNAL_SOURCES requests correction of one third-party source page that conflicts with a verified brand fact; CONTRADICTIONS_OWNED_SOURCES corrects one source page on a domain the brand owns; SEO_ISSUE and ROBOTS_TXT are technical fixes to a site the brand controls; PDP_OPTIMISATION improves one product page; MANUAL_ACTION is work a customer described themselves that matches none of the other shapes; CONTENT_OPTIMISATION improves an existing page the brand owns, and appears only on projects with content optimisation enabled — the optimize content endpoint returns its article and suggestions.

statusesstring[]

Defaults to every status. PENDING is a suggestion nobody has decided on, PLANNED is an action you wrote and have not started, ACCEPTED is in progress, COMPLETED is done, REJECTED was declined, EXPIRED was left untouched for 30 days and closed automatically.

categoriesstring[]

The off-site playbook a template action follows (the upper-case values), or the audit check an SEO_ISSUE came from (the lower-case ones). agent_readiness is the AI agent readiness audit, which covers files written for AI agents such as llms.txt. A playbook is orthogonal to the group, so the same one appears across groups, and narrowing by both means the intersection. Content briefs and ROBOTS_TXT actions carry none and match nothing here.

domainsstring[]

The site an SEO_ISSUE was raised against. Every other type carries none and matches nothing here.

topic_idsstring[]

Only actions on these topics (see the topics endpoint).

model_channel_idsstring[]

Only actions affecting these AI engine channels (see the model channels endpoint).

country_codesstring[]

ISO 3166-1 alpha-2 markets. An action carrying no markets is not scoped to one, so every selection matches it.

targetsstring[]

owned means the action lands on a page the brand controls; earned means a third-party page, which covers editorial coverage and community posts alike. A UGC action is earned even when the brand writes the post itself.

groupsstring[]

The kind of surface the action lands on.

archetypesstring[]

The kind of page a content brief says to create. Template actions carry no archetype and match nothing here, so this narrows the answer to content briefs.

platformsstring[]

Registrable domain of a third-party action. Own-site actions carry none and match nothing here.

order_by'impact' | 'created_at'

impact is the order the Actions page ranks by, strongest expected gain first. created_at reads newest first, which is how to find what Peec generated since the last read.

direction'asc' | 'desc'
limitinteger
offsetinteger

Example request

{
  "project_id": "or_f45b94ba-5e35-4982-93ed-285e72ee14eb",
  "domains": [
    "example.com"
  ],
  "topic_ids": [
    "to_a1b2c3"
  ],
  "model_channel_ids": [
    "openai-0"
  ],
  "country_codes": [
    "US"
  ],
  "platforms": [
    "reddit.com"
  ]
}

Response

Success

total_countnumber required

Actions matching the filters, ignoring pagination.

Example response

{
  "data": [
    {
      "id": "01a0422f-e0c4-7820-85a1-31515a321f15",
      "title": "Add a pricing comparison table to the plans page",
      "category": "EDITORIAL_PITCH",
      "platform": "reddit.com",
      "topic_id": "to_a1b2c3",
      "source": "https://example.com/pricing",
      "domain": "example.com",
      "created_at": "2026-08-20T10:12:00.000Z",
      "due_on": "2026-10-31"
    }
  ],
  "total_count": 42
}

Changes

  • 9d774600c8ebRevision changes
    • warning

      added the new exa-0 enum value to the /// response property for the response status

    • info

      added the new exa-0 enum value to the request property / (media type: application/json)

    • info

      added the new exa-0 enum value to the request property / (media type: application/x-www-form-urlencoded)

    • info

      added the new exa-0 enum value to the request property / (media type: multipart/form-data)

  • 9fdffdff48a5Revision changes
    • info

      endpoint added