Skip to content
SapphireIT Labs
Editorial Workflow documentation

REST API

Namespace: sit-cwm/v1 ÔÇö every route lives under https://example.com/wp-json/sit-cwm/v1/.

Everything the Gutenberg sidebar, the admin dashboard and the governance report do goes through these nine endpoints. There is no private AJAX action and no hidden path: the React app is a client of this API, and so can you be.

Nothing here is public. Every route has a real permission_callback; there is no __return_true anywhere in the plugin. Authorization is re-derived server-side on every request, so the capabilities and available_transitions a response hands you are display hints, never a grant.

Changes in 1.2

Everything below is additive: no field was removed or renamed, and 1.1 clients keep working unchanged.


Authenticating

From the browser (what the plugin’s own UI does)

@wordpress/api-fetch sends the wp_rest nonce with the logged-in session cookie. Nothing else is needed.

From outside WordPress (curl, scripts, CI)

Use an application password: Users  Profile  Application Passwords. Then send it as HTTP Basic auth.

export CWM_SITE="https://example.com"
export CWM_AUTH="editor:abcd EFGH ijkl MNOP qrst UVWX"   # user:application-password

curl -sS -u "$CWM_AUTH" "$CWM_SITE/wp-json/sit-cwm/v1/statuses" | jq

Every example below assumes those two variables. Application passwords require HTTPS unless the site defines WP_ENVIRONMENT_TYPE as local.


Endpoints at a glance

MethodRoutePurpose
GET/posts/{post_id}/workflowOne post’s workflow state
POST/posts/{post_id}/workflowChange status, reviewer, due date and/or declared AI origin
GET/posts/{post_id}/activityPaginated activity history
POST/posts/{post_id}/commentsAdd a workflow comment
GET/statusesStatus registry + transition map
GET/postsDashboard collection
GET/posts/summaryDashboard tile counts (since 1.2)
POST/posts/batchBulk status / reviewer / due date
GET/usersAssignable reviewers
GET/reports/governanceGovernance report (auditors only, since 1.2)

GET /posts/{post_id}/workflow

Current workflow state of one post, plus what this user may do with it next.

Permissions  logged in  the post exists, has a workflow, and is readable (otherwise 404)  the user can edit the post or view its activity.

Arguments

NameInTypeConstraints
post_idpathintegerrequired,  1

Example

curl -sS -u "$CWM_AUTH" "$CWM_SITE/wp-json/sit-cwm/v1/posts/125/workflow" | jq
{
  "post_id": 125,
  "post_title": "Q3 launch announcement",
  "post_type": "post",
  "post_status": "draft",
  "edit_link": "https://example.com/wp-admin/post.php?post=125&action=edit",
  "status": "review",
  "status_label": "Review",
  "status_is_unknown": false,
  "reviewer": {
    "id": 4,
    "name": "Dana Okafor",
    "avatar": "https://secure.gravatar.com/avatar/?s=48"
  },
  "due_date": "2026-10-02",
  "ai_origin": {
    "value": "ai_assisted",
    "label": "AI-assisted",
    "can_declare": true
  },
  "available_transitions": [
    { "slug": "approved",      "label": "Approved",      "is_forward": true,  "is_rollback": false },
    { "slug": "needs_changes", "label": "Needs Changes", "is_forward": false, "is_rollback": true  }
  ],
  "blocked_transitions": [],
  "capabilities": {
    "can_change_status": true,
    "can_assign_reviewer": true,
    "can_set_due_date": true,
    "can_comment": true,
    "can_view_activity": true
  },
  "publish_gate": {
    "mode": "enforce",
    "outcome": "refused"
  },
  "self_approval_blocked": false,
  "attestation": {
    "required": true,
    "statement": "I confirm I have reviewed this content and approve it for publication."
  }
}

post_status is the WordPress post status and is deliberately unrelated to status, the workflow status. status_is_unknown is true when the stored slug is no longer registered (a filter was removed); the default status is reported instead. reviewer is null when none is assigned, due_date is "" when unset.

publish_gate (since 1.1)

What the publish gate would do if the current user published this post now.

FieldValues
modeoff, log_only, enforce: the post type’s gate mode
outcomenot_applicable: the mode is off, or the post is already publish/future (the gate only judges a move into a published state). allowed: the workflow status passes the rule. bypassed: it does not pass, but the publish would go ahead and be recorded as a publish without approval (log_only, or enforce with sit_cwm_bypass_publish_gate). refused: enforce, and the user cannot bypass.

Like capabilities, it is a display hint for the editor’s notice. The gate re-decides on the actual write. It appears on GET and POST /posts/{post_id}/workflow only, not on GET /posts rows or batch items.

self_approval_blocked (since 1.1)

true only when the self-approval rule is the reason the current user is not offered approved: approved is a legal next step, the user holds sit_cwm_approve_content, they are the post’s author, and self-approval is prevented. Otherwise false. A display hint, like capabilities; same routes as publish_gate.

blocked_transitions (since 1.2)

Legal next steps that an extension has vetoed for the current user, with the reason, so a client can explain why a step is missing instead of just hiding it. Each entry is { slug, label, code, message }, in transition-map order:

"blocked_transitions": [
  {
    "slug": "approved",
    "label": "Approved",
    "code": "acme_checklist_incomplete",
    "message": "The legal checklist is not complete."
  }
]

An entry appears only when a sit_cwm_can_transition filter returned a WP_Error for a step the user’s capabilities would otherwise allow. Plain capability refusals are never listed, so a user learns nothing about rules for steps they could not take anyway. It never overlaps available_transitions. message is plain text: render it as text, never as HTML. Empty when nothing is vetoed. Not on dashboard rows.

ai_origin (since 1.2)

How the post was made, as declared by a person or a tool. The plugin never inspects content to detect it.

FieldValues
valuehuman, ai_assisted, ai_generated, or "" when nothing has been declared
labelHuman-written, AI-assisted, AI-generated or Not declared (translated)
can_declarewhether the current user may change it: sit_cwm_change_workflow plus edit_post on this post. A display hint, like capabilities

See Declaring AI use for how to set it.

attestation (since 1.2)

FieldValues
requiredtrue when moving this post to approved needs "attested": true (the site’s review attestation setting, then the sit_cwm_require_attestation filter)
statementthe statement the approver confirms (translated). It is stored with the approval in the activity log

A display hint, like capabilities. The server enforces the requirement on every route to approved, whatever this says.


POST /posts/{post_id}/workflow

Changes the status, the reviewer, the due date, the declared AI origin, or any combination. At least one must be present.

Permissions  logged in  post readable (404)  edit_post on it (403)  per field: sit_cwm_assign_reviewer for reviewer_id and due_date, sit_cwm_change_workflow for ai_origin (403)  for status, the full transition check (400/403/409, and 422 for an unattested approval that requires attestation). Everything is authorized before anything is written.

Arguments

NameInTypeConstraints
post_idpathintegerrequired,  1
statusbodystringone of the registered status slugs
frombodystringrequired whenever status is sent; the status the client believed was current
reviewer_idbodyinteger 0; 0 clears the reviewer. Must hold sit_cwm_review_content
due_datebodystringYYYY-MM-DD, or "" to clear
ai_originbodystringsince 1.2; one of human, ai_assisted, ai_generated. "" is rejected: a declaration can be changed but not withdrawn
attestedbodybooleansince 1.2; the user confirms they reviewed the content. Required with "status": "approved" when attestation.required is true. An attested approval stores the statement in its activity row, required or not

Unknown body fields are ignored.

Order of operations

Changes are applied AI origin  reviewer  due date  status, so a declaration sent with a status change is recorded before it. The write is not transactional: if a later step fails (a concurrent edit between the check and the write), the earlier steps stay applied. In practice the permission check has already validated every part, so this only triggers on a genuine race.

Example ÔÇö approve a post

curl -sS -u "$CWM_AUTH" -X POST 
  -H 'Content-Type: application/json' 
  -d '{"from":"review","status":"approved"}' 
  "$CWM_SITE/wp-json/sit-cwm/v1/posts/125/workflow" | jq

The response is the full workflow object above, freshly re-read ÔÇö same shape as GET.

Example ÔÇö assign a reviewer and a due date in one call

curl -sS -u "$CWM_AUTH" -X POST 
  -H 'Content-Type: application/json' 
  -d '{"reviewer_id":4,"due_date":"2026-10-02"}' 
  "$CWM_SITE/wp-json/sit-cwm/v1/posts/125/workflow" | jq

Example ÔÇö the concurrency guard firing

Someone else already sent the post back while you were reading it:

curl -sS -u "$CWM_AUTH" -X POST 
  -H 'Content-Type: application/json' 
  -d '{"from":"review","status":"approved"}' 
  "$CWM_SITE/wp-json/sit-cwm/v1/posts/125/workflow" -w 'n%{http_code}n'
{
  "code": "sit_cwm_status_conflict",
  "message": "The workflow status was changed by someone else. Reload and try again.",
  "data": { "status": 409 }
}
409

Nothing was written. Re-GET the workflow and decide again.


GET /posts/{post_id}/activity

One page of the post’s history, newest first.

Permissions  logged in  post readable (404)  sit_cwm_view_activity plus edit_post on the post (403).

Arguments

NameInTypeConstraints
post_idpathintegerrequired,  1
pagequeryinteger 1, default 1
per_pagequeryinteger1ÔÇô100, default 20
actionquerystringone of status_changed, reviewer_assigned, reviewer_cleared, due_date_set, due_date_cleared, comment_added, post_published, post_unpublished, publish_gate_refused, publish_gate_bypassed

Example

curl -sS -u "$CWM_AUTH" -D- 
  "$CWM_SITE/wp-json/sit-cwm/v1/posts/125/activity?per_page=3" | jq

Response headers carry the totals, WordPress-style:

X-WP-Total: 17
X-WP-TotalPages: 6
[
  {
    "id": 412,
    "action": "status_changed",
    "action_label": "Status changed",
    "old_value": "writing",
    "old_label": "Writing",
    "new_value": "review",
    "new_label": "Review",
    "message": "",
    "created_at": "2026-09-16T14:22:08+00:00",
    "created_at_human": "18 hours ago",
    "user_id": 7,
    "user": { "id": 7, "name": "Sam Idrissi", "avatar": "https://" },
    "workflow_status": null,
    "workflow_status_label": null,
    "gate_reason": null,
    "attested": null,
    "attestation": null
  },
  {
    "id": 411,
    "action": "comment_added",
    "action_label": "Comment added",
    "old_value": null,
    "old_label": null,
    "new_value": null,
    "new_label": null,
    "message": "Second half needs a source.",
    "created_at": "2026-09-16T14:20:51+00:00",
    "created_at_human": "18 hours ago",
    "user_id": 4,
    "user": { "id": 4, "name": "Dana Okafor", "avatar": "https://" },
    "workflow_status": null,
    "workflow_status_label": null,
    "gate_reason": null,
    "attested": null,
    "attestation": null
  },
  {
    "id": 409,
    "action": "publish_gate_bypassed",
    "action_label": "Published without approval",
    "old_value": "draft",
    "old_label": "Draft",
    "new_value": "publish",
    "new_label": "Published",
    "message": "",
    "created_at": "2026-09-16T09:02:13+00:00",
    "created_at_human": "1 day ago",
    "user_id": 1,
    "user": { "id": 1, "name": "Site Admin", "avatar": "https://" },
    "workflow_status": "review",
    "workflow_status_label": "Review",
    "gate_reason": "capability",
    "attested": null,
    "attestation": null
  }
]

created_at is always ISO 8601 in UTC. user_id is 0 for system-generated rows; a non-zero user_id with "user": null means the account was deleted. old_label/new_label resolve slugs and user IDs to display names so a client does not have to.

Publication entries (since 1.1)

actionaction_labelold_value  new_value
post_publishedPublishedprevious post status  publish
post_unpublishedUnpublishedpublish  new post status (including trash)
publish_gate_refusedPublishing blockedstored post status  attempted publish/future
publish_gate_bypassedPublished without approvalstored post status  publish

For these four, old_value/new_value are WordPress post statuses, not workflow statuses, and old_label/new_label are post status labels (new and auto-draft are labelled “New”). user_id is 0 for scheduled publishing and for WP-CLI without --user.

Every item carries three more fields, null for the 1.0 actions:

FieldTypeMeaning
workflow_statusstring | nullThe workflow status slug at the moment of the publication event
workflow_status_labelstring | nullIts label
gate_reasonstring | nullOn publish_gate_bypassed only: log_only, capability (the bypass capability) or error (a gate layer failed open)

AI use entries (since 1.2)

actionaction_labelold_value  new_value
ai_origin_changedAI use declaredprevious declaration (null when nothing was declared)  human, ai_assisted or ai_generated

old_label/new_label carry the translated labels (old_label is null when nothing was declared before). How the declaration arrived (workflow, post_api or default, see Declaring AI use) is kept in the row’s context and appears in the CSV export’s via column. Since 1.2, post_published and post_unpublished rows also record the post’s declared AI use at that moment (none when nothing was declared). It is in the CSV export’s ai_origin column and feeds the governance report.

Attested approvals (since 1.2)

Every item also carries attested (boolean | null) and attestation (string | null). On a status_changed row for an approval sent with "attested": true they are true and the exact statement the approver confirmed, as plain text. They are null on every other row.


POST /posts/{post_id}/comments

Adds a workflow comment. These live in the activity table, not in wp_comments, and never appear on the front end.

Permissions  logged in  post readable (404)  sit_cwm_view_activity plus edit_post (403).

Arguments

NameInTypeConstraints
post_idpathintegerrequired,  1
messagebodystringrequired, Ôëñ 5000 characters, must contain visible text after wp_kses_post()

Example

curl -sS -u "$CWM_AUTH" -X POST 
  -H 'Content-Type: application/json' 
  -d '{"message":"Second half needs a source."}' 
  "$CWM_SITE/wp-json/sit-cwm/v1/posts/125/comments" -w 'n%{http_code}n'

Returns 201 with the stored activity entry, shaped exactly like an item from GET /activity.


GET /statuses

The status registry and the transition graph. Display metadata for building a UI ÔÇö it says nothing about what the current user may do on any particular post; that comes from a post’s available_transitions.

Permissions  logged in  sit_cwm_manage_workflows or WordPress edit_posts.

Example

curl -sS -u "$CWM_AUTH" "$CWM_SITE/wp-json/sit-cwm/v1/statuses" | jq
{
  "default_status": "draft",
  "statuses": [
    {
      "slug": "draft",
      "label": "Draft",
      "description": "Not yet started in the workflow.",
      "color": "#757575",
      "order": 10,
      "is_final": false
    },
    { "slug": "writing", "label": "Writing", "": "" },
    { "slug": "review", "label": "Review", "": "" },
    { "slug": "needs_changes", "label": "Needs Changes", "": "" },
    { "slug": "approved", "label": "Approved", "": "" },
    { "slug": "published", "label": "Published", "color": "#2271b1", "order": 60, "is_final": true }
  ],
  "transitions": {
    "draft":         [ { "slug": "writing", "label": "Writing", "is_forward": true, "is_rollback": false } ],
    "writing":       [ { "slug": "review", "label": "Review", "is_forward": true, "is_rollback": false } ],
    "review":        [ { "slug": "approved", "": "" }, { "slug": "needs_changes", "is_rollback": true, "": "" } ],
    "needs_changes": [ { "slug": "writing", "": "" } ],
    "approved":      [ { "slug": "published", "": "" }, { "slug": "needs_changes", "is_rollback": true, "": "" } ],
    "published":     [ { "slug": "writing", "is_rollback": true, "": "" } ]
  }
}

GET /posts

The dashboard collection: workflow-managed posts, filtered, sorted and paginated server-side. Nothing here loads every row.

Permissions ÔÇö logged in ÔåÆ able to edit content of at least one workflow-enabled post type (403 otherwise, and 403 for a post_type outside that set). Users who cannot edit others’ posts only see posts they authored or are assigned to review; that scope is part of the SQL query, not a post-filter.

Arguments

NameTypeConstraintsDefault
pageinteger 11
per_pageinteger1ÔÇô10020
searchstringÔëñ 200 charactersÔÇö
statusarray of stringeach a registered status slugÔÇö
reviewer_idinteger 0; 0 matches posts with no reviewer
authorinteger 1
post_typestringone workflow-enabled post typeÔÇö
due_beforestringYYYY-MM-DDÔÇö
due_afterstringYYYY-MM-DDÔÇö
overduebooleandue date passed, in the site timezone, while the status is non-finalÔÇö
orderbystringtitle, date, due_date, statusdate
orderstringasc, descdesc

Repeat status[] for several values, or send a comma-separated list.

Example

curl -sS -u "$CWM_AUTH" -D- -G 
  --data-urlencode 'status[]=review' 
  --data-urlencode 'status[]=needs_changes' 
  --data-urlencode 'overdue=true' 
  --data-urlencode 'orderby=due_date' 
  --data-urlencode 'order=asc' 
  --data-urlencode 'per_page=2' 
  "$CWM_SITE/wp-json/sit-cwm/v1/posts" | jq
[
  {
    "post_id": 125,
    "title": "Q3 launch announcement",
    "post_type": "post",
    "post_status": "draft",
    "author": { "id": 7, "name": "Sam Idrissi" },
    "status": "review",
    "status_label": "Review",
    "status_is_unknown": false,
    "reviewer": { "id": 4, "name": "Dana Okafor", "avatar": "https://" },
    "due_date": "2026-09-12",
    "is_overdue": true,
    "ai_origin": "ai_assisted",
    "last_activity": {
      "id": 412,
      "action": "status_changed",
      "action_label": "Status changed",
      "new_value": "review",
      "new_label": "Review",
      "created_at": "2026-09-16T14:22:08+00:00",
      "created_at_human": "18 hours ago",
      "user_id": 7,
      "user": { "id": 7, "name": "Sam Idrissi", "avatar": "https://" }
    },
    "edit_link": "https://example.com/wp-admin/post.php?post=125&action=edit",
    "available_transitions": [ { "slug": "approved", "": "" } ],
    "capabilities": { "can_change_status": true, "": "" }
  }
]

With X-WP-Total and X-WP-TotalPages headers. title is the raw post title ÔÇö escape it at output. edit_link is "" when the user cannot edit the post. ai_origin (since 1.2) is the declared value, "" when nothing was declared; unlike the workflow route it is a bare string, with no label or hint.

Since 1.2, a row may carry extra keys from an add-on (sit_cwm_posts_item). The keys above are always Free’s, so ignore any you do not know.

One page costs a fixed number of queries regardless of its size: the reviewer, author and last-activity lookups are batch-loaded, not per row.


GET /posts/summary

Since 1.2. The counts behind the dashboard’s summary tiles. Same permission and scoping as GET /posts: the user’s workflow-enabled post types and, for users who cannot see all of them, only content they author or review. Takes no arguments; the sit_cwm_posts_query_args filter does not apply.

FieldMeaning
in_reviewContent in Review, or a status an add-on counts as review
in_review_mineThe same content, with the current user as reviewer
needs_changesContent in Needs Changes
overdueContent past its due date and not in a final status
approvedContent Approved and not yet Published in the workflow
review_statusesThe status slugs in_review counts; ["review"] unless an add-on adds to it
curl -sS -u "$CWM_AUTH" "$CWM_SITE/wp-json/sit-cwm/v1/posts/summary" | jq
{ "in_review": 12, "in_review_mine": 3, "needs_changes": 4, "overdue": 3, "approved": 5, "review_statuses": [ "review" ] }

Errors: rest_forbidden (401) when logged out, sit_cwm_forbidden (403) without dashboard access.


POST /posts/batch

Applies one action to up to 100 posts.

Permissions  logged in  sit_cwm_manage_workflows or edit_posts. That check only gates the attempt. Every post in the batch re-runs the identical single-item code path, including its own authorization, so a batch can never do anything the same requests sent one at a time could not.

Arguments

NameTypeConstraints
post_idsarray of integerrequired, 1100 items, each  1. Duplicates are processed once
actionstringrequired: change_status, assign_reviewer or set_due_date
payloadobjectrequired; exactly the key the action needs, no others (except the optional attested with change_status)
actionrequired payload key
change_statusstatus ÔÇö a registered status slug. Since 1.2 it may add attested (boolean), which applies to every post in the batch: required to approve when attestation is required
assign_reviewerreviewer_id  integer  0, 0 clears
set_due_datedue_date ÔÇö YYYY-MM-DD, or "" to clear

change_status starts from each post’s own current status. The client cannot supply one from for many posts, so a post whose current status makes the move illegal fails rather than being forced.

Example

curl -sS -u "$CWM_AUTH" -X POST 
  -H 'Content-Type: application/json' 
  -d '{"post_ids":[125,126,999],"action":"change_status","payload":{"status":"approved"}}' 
  "$CWM_SITE/wp-json/sit-cwm/v1/posts/batch" -w 'n%{http_code}n' | jq
{
  "succeeded": [ 125 ],
  "failed": [
    {
      "post_id": 126,
      "code": "sit_cwm_invalid_transition",
      "message": "This workflow transition is not allowed.",
      "status": 400
    },
    {
      "post_id": 999,
      "code": "sit_cwm_invalid_post",
      "message": "No workflow content was found with this ID.",
      "status": 404
    }
  ],
  "items": [ { "post_id": 125, "status": "approved", "": "" } ]
}
200

A partly-failed batch is still HTTP 200 ÔÇö per-item outcomes live in the body. items holds the fresh workflow state of each success, so a client can update its rows without refetching. Only a request malformed as a whole is a 400: zero or more than 100 IDs, an unknown action, a payload missing the action’s key or carrying an unknown one.

Missing, trashed, non-workflow and unreadable posts all fail with the identical sit_cwm_invalid_post entry ÔÇö the batch endpoint is not a post-ID oracle.

Every success writes its own activity row and fires its own action hook. There is no aggregate event.


GET /users

Users who may be assigned as a reviewer: those holding sit_cwm_review_content.

Permissions ÔÇö logged in ÔåÆ with post_id, the post must be readable (404) and the user must be able to assign that post’s reviewer; without it, sit_cwm_assign_reviewer or sit_cwm_manage_workflows.

This is a classic user-enumeration hole, so it is deliberately narrow: responses carry id, display name and avatar only, and search matches display name and nicename ÔÇö never logins or email addresses.

Arguments

NameTypeConstraints
searchstringÔëñ 100 characters
per_pageinteger1ÔÇô100, default 20
post_idintegerÔëÑ 1; scopes the list to users who can review that post. Since 1.1, leaves out the post’s author while self-approval is prevented

Example

curl -sS -u "$CWM_AUTH" -G 
  --data-urlencode 'post_id=125' 
  --data-urlencode 'search=dana' 
  "$CWM_SITE/wp-json/sit-cwm/v1/users" | jq
[
  { "id": 4, "name": "Dana Okafor", "avatar": "https://secure.gravatar.com/avatar/?s=48" }
]

GET /reports/governance

Since 1.2. Site-wide governance figures for a period: how much of what was published had passed approval, how much went out while the publish gate was off or in log-only mode, gate refusals and bypasses, declared AI use and overdue reviews. Read-only; nothing is cached.

Permissions  logged in (401)  sit_cwm_view_activity and sit_cwm_manage_workflows (403 sit_cwm_forbidden). Administrators only by default  the same rule as the activity CSV export.

Arguments

NameTypeConstraints
periodinteger30, 90 or 365 days, default 90. Anything else is 400 rest_invalid_param

Example

curl -sS -u "$CWM_AUTH" -G --data-urlencode 'period=90' 
  "$CWM_SITE/wp-json/sit-cwm/v1/reports/governance" | jq
{
  "period_days": 90,
  "since": "2026-07-31T00:00:00Z",
  "generated_at": "2026-10-29T10:00:00Z",
  "publication": {
    "total": 4,
    "approved": 2,
    "approved_share": 0.5,
    "by_gate_mode": { "off": 1, "log_only": 1, "enforce": 1, "unknown": 1 }
  },
  "gate": {
    "refused": 1,
    "bypassed": { "log_only": 2, "capability": 1, "error": 0 }
  },
  "ai_origin": {
    "current":   { "human": 12, "ai_assisted": 3, "ai_generated": 1, "not_declared": 40 },
    "published": { "human": 1, "ai_assisted": 0, "ai_generated": 1, "not_declared": 1, "not_recorded": 1 }
  },
  "overdue": { "count": 2 }
}

Definitions

  • In the period means the activity row’s created_at >= since, where since is midnight UTC period_days days ago. All times are UTC.
  • publication.total: post_published rows in the period.
  • publication.approved: those whose workflow status at publication was approved or published.
  • publication.approved_share: approved / total, rounded to 4 decimals; null when total is 0.
  • publication.by_gate_mode: the gate mode at publication. Rows written before 1.1 carry none and count as unknown. “Published while the gate was off or in log-only mode” is off + log_only.
  • gate.refused: publish_gate_refused rows in the period.
  • gate.bypassed: publish_gate_bypassed rows in the period, by reason. Unknown reasons are not counted.
  • ai_origin.current: the declared AI origin of every post of a workflow-enabled type right now, except trashed posts and auto-drafts. Undeclared posts are not_declared.
  • ai_origin.published: the declaration recorded on each post_published row in the period. not_declared means nothing was declared at the time; not_recorded means the row predates 1.2 and recorded nothing. Neither is ever counted as a declaration.
  • overdue.count: workflow-managed posts past their due date and not in a final status, site-wide (not limited to the viewer’s own posts).

AI origin is declared, not detected: these counts report what people said, never an analysis of the content.


Declaring AI use

Since 1.2 a post can declare how it was made: human, ai_assisted or ai_generated. The value is declared, not detected. Nothing in the plugin inspects content. Until something is declared it reads as "" (“Not declared”). A declaration can be changed but never withdrawn back to "".

Declaring needs sit_cwm_change_workflow and edit_post on the post, so an author can declare on their own posts but not on others’. Declaring the value the post already has is a no-op and logs nothing. Each real change is logged as ai_origin_changed, with a via value in its context:

viaArrived by
workflowPOST /sit-cwm/v1/posts/{post_id}/workflow (the sidebar, the classic box, agents working in steps)
post_apithe sit_cwm_ai_origin field on core’s wp/v2 post routes
defaultthe post type’s default, stamped once when a post is created with nothing declared

There are two ways to declare.

On the workflow route

Send ai_origin alone or with other changes. It is applied first:

curl -sS -u "$CWM_AUTH" -X POST 
  -H 'Content-Type: application/json' 
  -d '{"ai_origin":"ai_generated","from":"draft","status":"writing"}' 
  "$CWM_SITE/wp-json/sit-cwm/v1/posts/125/workflow" | jq '.ai_origin, .status'
{ "value": "ai_generated", "label": "AI-generated", "can_declare": true }
"writing"

On core’s post routes (wp/v2)

Every workflow-enabled post type gets a sit_cwm_ai_origin field on /wp/v2/{rest_base}. An agent can create a draft and declare its origin in one call:

curl -sS -u "$CWM_AUTH" -X POST 
  -H 'Content-Type: application/json' 
  -d '{"title":"Agent draft","status":"draft","sit_cwm_ai_origin":"ai_generated"}' 
  "$CWM_SITE/wp-json/wp/v2/posts" | jq '{id, sit_cwm_ai_origin}'
{ "id": 131, "sit_cwm_ai_origin": "ai_generated" }

That logs one ai_origin_changed entry with via: post_api. The type’s default is not stamped on top, because the field is saved before the default would be applied.

  • The field is in the edit context only. Reading it needs ?context=edit, which core allows only to users who can edit the post. It never appears in public view responses.
  • It accepts "" and ignores it, so a client can send back the post it read. Any other value outside the enum is 400 rest_invalid_param.
  • A user who can edit the post but lacks sit_cwm_change_workflow gets 403 sit_cwm_forbidden, and nothing is declared.
  • A rejected field does not undo the post write. This is core behaviour: core saves the post first and the extra fields after it. A POST /wp/v2/posts whose sit_cwm_ai_origin is refused still creates the post (and an update still saves its other fields), but the response is the error, not the post. Agents should check the response status and, on a refused create, look the draft up or declare again through the workflow route. A create whose field is refused is not stamped with the type’s default either.
  • Post types that are not workflow-enabled do not get the field.

Errors

Errors are standard WordPress WP_Error JSON:

{
  "code": "sit_cwm_forbidden",
  "message": "You are not allowed to perform this workflow action.",
  "data": { "status": 403 }
}

Error codes

CodeHTTPMeaning
rest_forbidden401Not logged in.
sit_cwm_forbidden403Logged in, post visible, but not allowed to do this.
sit_cwm_self_approval403Since 1.1. Moving your own post to approved while self-approval is prevented. From POST /posts/{post_id}/workflow and per item from the batch route.
sit_cwm_attestation_required422Since 1.2. Moving a post to approved without "attested": true while attestation is required for it. From POST /posts/{post_id}/workflow and per item from the batch route. A user who may not approve gets 403 instead.
sit_cwm_not_managed404The post is missing, has no workflow, or is not readable by you. Deliberately indistinguishable ÔÇö see below.
sit_cwm_invalid_post404Per-batch-item equivalent of the above.
sit_cwm_invalid_status400status is not a registered slug.
sit_cwm_invalid_transition400That edge is not in the transition graph from the post’s current status.
sit_cwm_invalid_user400The reviewer does not exist, does not hold sit_cwm_review_content, or is the post’s author while self-approval is prevented.
sit_cwm_invalid_date400The due date is not a real YYYY-MM-DD date.
sit_cwm_invalid_ai_origin400Since 1.2. The AI origin is not human, ai_assisted or ai_generated. Usually caught earlier as rest_invalid_param.
sit_cwm_invalid_batch400Fewer than 1 or more than 100 IDs, unknown action, or a mismatched payload.
sit_cwm_empty_comment400The comment has no visible text after sanitizing.
sit_cwm_comment_too_long400Over 5000 characters.
sit_cwm_status_conflict409from does not match the stored status; someone else moved the post. Nothing was written.
sit_cwm_update_failed500The database write failed after every check passed.
sit_cwm_publish_gated403Returned by core’s wp/v2 routes, not this namespace: the publish gate refused a create or update into publish/future. See Core routes.
rest_missing_callback_param400A required argument is absent ÔÇö including from when status is sent.
rest_invalid_param400An argument failed its schema (type, enum, range, length).

Extension vetoes

Since 1.2, an add-on can refuse a status change with its own reason by returning a WP_Error from the sit_cwm_can_transition filter. The workflow route (and each batch item) then answers with that code and message, and an HTTP status between 400 and 499 (403 unless the extension chose another):

{
  "code": "acme_checklist_incomplete",
  "message": "The legal checklist is not complete.",
  "data": { "status": 422 }
}

A user who lacks the capability for that step gets the generic sit_cwm_forbidden instead, never the extension’s reason. The same vetoes are listed ahead of time in blocked_transitions.

Why 404 and not 403

A post you cannot read, a post that does not exist, and a post whose type has no workflow all return the identical sit_cwm_not_managed 404 ÔÇö same code, same message, same status. A 403 is only ever returned for a post you can already see. Otherwise the difference between the two responses would let anyone enumerate private post IDs.

Check order

Each permission callback runs: authenticated  capability  access to this specific post  transition validity, in that order, entirely server-side.

One core behaviour to be aware of: WordPress validates the argument schema before calling permission_callback, so a malformed request can answer 400 before it would have answered 401 or 403. That is core’s ordering, not the plugin’s.

Errors leak nothing

Messages are generic by design. They never include post titles, content, usernames or email addresses.


Core routes (wp/v2)

The plugin adds no routes outside sit-cwm/v1. Since 1.2 it adds one field, sit_cwm_ai_origin, to the post routes of workflow-enabled types (see Declaring AI use). And when a post type’s publish gate is set to enforce it changes two things about core’s wp/v2 post routes for that type:

  • Create and update can return sit_cwm_publish_gated (403). A request that would move a post into publish or future while its workflow status is not approved/published, by a user without sit_cwm_bypass_publish_gate, is refused before anything is written:
{
  "code": "sit_cwm_publish_gated",
  "message": "This content has to be approved in the editorial workflow before it can be published.",
  "data": { "status": 403 }
}

Updating a post that is already publish is never gated, so a live post in re-review can still be saved. A refusal on an existing post is recorded as publish_gate_refused; a refused create is not, because no post exists yet.

  • The wp:action-publish link is removed from context=edit responses when the gate would refuse this user. The block editor reads that link, so it offers Submit for Review instead of Publish.

In log_only neither happens: the write goes through, and when the post goes live the publish is recorded as publish_gate_bypassed with gate_reason log_only.


Discovering the schema

Every route publishes a JSON Schema. To read it:

curl -sS -u "$CWM_AUTH" "$CWM_SITE/wp-json/sit-cwm/v1" | jq '.routes | keys'
curl -sS -u "$CWM_AUTH" -X OPTIONS "$CWM_SITE/wp-json/sit-cwm/v1/posts" | jq '.endpoints[0].args'

Last updated:

Black Friday sale

Black Friday: 80% off every Pro plugin

Your first year, on every plan. The coupon is added for you at checkout.

Ends in The offer ends at 00:00 GMT on 5 December 2026.

Claim deal