MavertoMaverto
External REST API

Build against Maverto without reverse-engineering the product.

This page documents the public developer API exposed at/api/external/v1including auth flow, role boundaries, payload shapes, and working request examples.

Per-company API keysShort-lived bearer tokensRBAC-enforced routesWebhook delivery logs

Auth flow

  1. Create or rotate an API key in Dashboard, then open Settings and API.
  2. Exchange that key on POST /auth/token.
  3. Use the issued bearer token for all resource calls.
  4. Revoke tokens when rotating credentials or ending a session.

Base URL and headers

All public routes are mounted under /api/external/v1. Use a dashboard-issued API key only for token exchange. All resource operations should use Authorization: Bearer <token>.

Full base URL: https://api.maverto.com/api/external/v1

Responses are JSON envelopes. List routes return data[] plus pagination-ready meta. Mutation routes return a single data object.

Security notes

API keys are company-scoped and should be stored in a secret manager.

Webhook target URLs must be public HTTPS endpoints.

Rate limits are enforced per integration identity.

Permissions are checked per route. The gateway stays thin and does not bypass domain RBAC.

Endpoint reference

Expand any route to see exactly what goes in and what comes back

Each endpoint below can be expanded inline. That keeps request fields, response fields, and practical notes next to the route itself instead of in a separate schema section.

Authentication

Exchange an API key for a short-lived bearer token, inspect the active actor, and revoke issued tokens.

4 routes
POST

/auth/token

Exchange a dashboard-issued API key for a bearer token.

Scope: api_key

Summary

Exchange a dashboard-issued API key for a bearer token.

Request fields

api_key

Type: string

Required: yes

Notes: Dashboard-generated API key, used only on POST /auth/token.

Response fields

access_token

Type: string

Required: yes

Notes: Short-lived bearer token returned by token exchange.

token_type

Type: string

Required: yes

Notes: Always Bearer.

expires_in

Type: number

Required: yes

Notes: Token lifetime in seconds.

actor.user_id

Type: string

Required: yes

Notes: Authenticated external actor used for permission checks.

actor.integration_id

Type: string

Required: no

Notes: Diagnostic integration identifier, useful for support and tracing.

Notes

  • Use the API key only here; all resource calls should switch to bearer auth.
GET

/auth/me

Return the current external actor, role, and company context for the active token.

Scope: authenticated

Summary

Return the current external actor, role, and company context for the active token.

Response fields

actor.user_id

Type: string

Required: yes

Notes: Authenticated external actor used for permission checks.

actor.email

Type: string

Required: no

Notes: Actor email when available.

actor.role

Type: string

Required: yes

Notes: Current actor role used for authorization.

actor.company_id

Type: string

Required: yes

Notes: Company context bound to the integration.

actor.integration_id

Type: string

Required: no

Notes: Diagnostic integration identifier, useful for support and tracing.

POST

/auth/revoke

Revoke the currently used bearer token.

Scope: authenticated

Summary

Revoke the currently used bearer token.

Request fields

token

Type: string

Required: yes

Notes: Bearer token to revoke on POST /auth/revoke.

Response fields

data.success

Type: boolean

Required: yes

Notes: Mutation result for delete or revoke style operations.

GET

/usage

Return per-integration usage metrics and route-level request summary.

Scope: authenticated

Summary

Return per-integration usage metrics and route-level request summary.

Response fields

data.routes[]

Type: object[]

Required: yes

Notes: Per-route request totals and latency summary.

data.total_requests

Type: number

Required: yes

Notes: Total requests observed for this integration identity.

data.error_count

Type: number

Required: yes

Notes: Requests that ended with an error response.

Notes

  • Usage is scoped to the current integration identity, not global platform traffic.

Workspaces

Discover accessible workspaces and inspect one workspace in detail.

2 routes
GET

/workspaces

List workspaces the integration can access.

Scope: read

Summary

List workspaces the integration can access.

Response fields

data[]

Type: Workspace[]

Required: yes

Notes: List of workspaces available to the integration.

meta.total

Type: number

Required: yes

Notes: Total accessible workspaces returned in this full list response.

Referenced type fields

Workspace fields

id

Type: string

Required: yes

Notes: Workspace identifier.

name

Type: string

Required: yes

Notes: Human-readable workspace name.

company_id

Type: string

Required: yes

Notes: Owning company.

permissions

Type: string[]

Required: yes

Notes: Effective permissions for the current integration actor.

Notes

  • This route currently returns the full accessible workspace list and only exposes meta.total.
GET

/workspaces/{workspaceId}

Return one workspace by ID.

Scope: read

Summary

Return one workspace by ID.

Response fields

id

Type: string

Required: yes

Notes: Workspace identifier.

name

Type: string

Required: yes

Notes: Human-readable workspace name.

company_id

Type: string

Required: yes

Notes: Owning company.

permissions

Type: string[]

Required: yes

Notes: Effective permissions for the current integration actor.

Notes

  • Workspace path params always scope nested resources to a single workspace boundary.

Members

Manage workspace memberships with explicit role boundaries.

4 routes
GET

/workspaces/{workspaceId}/members

List workspace members.

Scope: manage_members

Summary

List workspace members.

Request fields

page

Type: number

Required: no

Notes: 1-based page number. Defaults to 1.

page_size

Type: number

Required: no

Notes: Items per page. Defaults to 20 unless noted otherwise on the route.

search

Type: string

Required: no

Notes: Optional member search filter.

Response fields

data[]

Type: Member[]

Required: yes

Notes: Workspace member list.

meta.total

Type: number

Required: yes

Notes: Total matching members.

meta.page

Type: number

Required: yes

Notes: Current 1-based page number.

meta.page_size

Type: number

Required: yes

Notes: Page size applied to this response.

meta.total_pages

Type: number

Required: yes

Notes: Total available pages.

Referenced type fields

Member fields

user_id

Type: string

Required: yes

Notes: Member user identifier.

role

Type: string

Required: yes

Notes: Current workspace role.

workspace_id

Type: string

Required: yes

Notes: Workspace the membership belongs to.

Notes

  • Workspace path params always scope nested resources to a single workspace boundary.
POST

/workspaces/{workspaceId}/members

Add a member to a workspace.

Scope: manage_members

Summary

Add a member to a workspace.

Request fields

user_id

Type: string

Required: yes

Notes: User to add or target for updates.

role

Type: string

Required: yes

Notes: Workspace role such as owner, member, or viewer.

Response fields

user_id

Type: string

Required: yes

Notes: Member user identifier.

role

Type: string

Required: yes

Notes: Current workspace role.

workspace_id

Type: string

Required: yes

Notes: Workspace the membership belongs to.

PATCH

/workspaces/{workspaceId}/members/{userId}

Change a member role.

Scope: manage_members

Summary

Change a member role.

Request fields

role

Type: string

Required: yes

Notes: New workspace role for the member identified in the path.

Response fields

user_id

Type: string

Required: yes

Notes: Member user identifier.

role

Type: string

Required: yes

Notes: Current workspace role.

workspace_id

Type: string

Required: yes

Notes: Workspace the membership belongs to.

DELETE

/workspaces/{workspaceId}/members/{userId}

Remove a member from the workspace.

Scope: manage_members

Summary

Remove a member from the workspace.

Response fields

data.success

Type: boolean

Required: yes

Notes: Mutation result for delete or revoke style operations.

Content

Create, update, publish, archive, verify, and discover content attached to a workspace.

12 routes
GET

/workspaces/{workspaceId}/content

List content in the workspace.

Scope: read_content

Summary

List content in the workspace.

Request fields

page

Type: number

Required: no

Notes: 1-based page number. Defaults to 1.

page_size

Type: number

Required: no

Notes: Items per page. Defaults to 20 unless noted otherwise on the route.

search

Type: string

Required: no

Notes: Full-text search filter.

status

Type: string

Required: no

Notes: Optional lifecycle status filter.

type

Type: string

Required: no

Notes: Optional content type filter.

tags

Type: string

Required: no

Notes: Comma-separated tag filter.

Response fields

data[]

Type: Content[]

Required: yes

Notes: List of content envelopes for the workspace.

meta.total

Type: number

Required: yes

Notes: Total records available for pagination.

meta.page

Type: number

Required: yes

Notes: Current 1-based page number.

meta.page_size

Type: number

Required: yes

Notes: Page size applied to this response.

meta.total_pages

Type: number

Required: yes

Notes: Total number of pages for the current filter set.

Referenced type fields

Content fields

id

Type: string

Required: yes

Notes: Content identifier.

workspace_id

Type: string

Required: yes

Notes: Owning workspace.

type

Type: string

Required: yes

Notes: Content type such as note, sop, decision, update, guide, video, or shadow_recording.

title

Type: string

Required: yes

Notes: Content title.

body

Type: string

Required: yes

Notes: Primary body text for the content item.

status

Type: string

Required: yes

Notes: draft, published, archived, or verified lifecycle state.

tags

Type: string[]

Required: no

Notes: Current tag set.

created_by

Type: string

Required: yes

Notes: User who created the content.

updated_by

Type: string

Required: yes

Notes: User who last updated the content.

created_at

Type: string

Required: yes

Notes: RFC3339 creation timestamp.

updated_at

Type: string

Required: yes

Notes: RFC3339 timestamp.

version

Type: number

Required: yes

Notes: Optimistic version counter.

verification_state

Type: string

Required: yes

Notes: verified or needs_review.

owner_user_id

Type: string

Required: yes

Notes: Current content owner ID, may be empty.

owner_name

Type: string

Required: no

Notes: Owner display name when cached.

owner_email

Type: string

Required: no

Notes: Owner email when cached.

timezone

Type: string

Required: yes

Notes: Workspace timezone.

is_pinned

Type: boolean

Required: yes

Notes: Pinned content is surfaced first in listings.

review_interval_days

Type: number

Required: no

Notes: Review cadence when configured.

last_verified_at

Type: string

Required: no

Notes: RFC3339 timestamp for the last verification event.

next_review_at

Type: string

Required: no

Notes: RFC3339 timestamp for the next review due date.

decision_summary

Type: string

Required: no

Notes: Decision-specific summary field when relevant.

decision_date

Type: string

Required: no

Notes: Decision date when present.

sop_steps

Type: string

Required: no

Notes: SOP steps text when relevant.

guide_steps[]

Type: object[]

Required: no

Notes: Guide step objects with selector and text.

recording_steps[]

Type: object[]

Required: no

Notes: Shadow recording step objects including action, selector, label, and attachment links.

attachments

Type: not_embedded

Required: n/a

Notes: Attachments are fetched separately via the attachments endpoints and are not embedded in GetContent.

video_fields

Type: not_separate

Required: n/a

Notes: Video uses type=video, but the current external JSON does not expose a dedicated video-specific sub-object.

Notes

  • Workspace path params always scope nested resources to a single workspace boundary.
POST

/workspaces/{workspaceId}/content

Create a content item.

Scope: write_content

Summary

Create a content item.

Request fields

type

Type: string

Required: yes

Notes: Content type such as note, sop, guide, or update.

title

Type: string

Required: yes

Notes: Title shown in the product UI.

body

Type: string

Required: yes

Notes: Main content body. Publish checks require enough text.

tags

Type: string[]

Required: no

Notes: Optional tags for filtering and discovery.

Response fields

id

Type: string

Required: yes

Notes: Content identifier.

workspace_id

Type: string

Required: yes

Notes: Owning workspace.

type

Type: string

Required: yes

Notes: Content type such as note, sop, decision, update, guide, video, or shadow_recording.

title

Type: string

Required: yes

Notes: Content title.

body

Type: string

Required: yes

Notes: Primary body text for the content item.

status

Type: string

Required: yes

Notes: draft, published, archived, or verified lifecycle state.

tags

Type: string[]

Required: no

Notes: Current tag set.

created_by

Type: string

Required: yes

Notes: User who created the content.

updated_by

Type: string

Required: yes

Notes: User who last updated the content.

created_at

Type: string

Required: yes

Notes: RFC3339 creation timestamp.

updated_at

Type: string

Required: yes

Notes: RFC3339 timestamp.

version

Type: number

Required: yes

Notes: Optimistic version counter.

verification_state

Type: string

Required: yes

Notes: verified or needs_review.

owner_user_id

Type: string

Required: yes

Notes: Current content owner ID, may be empty.

owner_name

Type: string

Required: no

Notes: Owner display name when cached.

owner_email

Type: string

Required: no

Notes: Owner email when cached.

timezone

Type: string

Required: yes

Notes: Workspace timezone.

is_pinned

Type: boolean

Required: yes

Notes: Pinned content is surfaced first in listings.

review_interval_days

Type: number

Required: no

Notes: Review cadence when configured.

last_verified_at

Type: string

Required: no

Notes: RFC3339 timestamp for the last verification event.

next_review_at

Type: string

Required: no

Notes: RFC3339 timestamp for the next review due date.

decision_summary

Type: string

Required: no

Notes: Decision-specific summary field when relevant.

decision_date

Type: string

Required: no

Notes: Decision date when present.

sop_steps

Type: string

Required: no

Notes: SOP steps text when relevant.

guide_steps[]

Type: object[]

Required: no

Notes: Guide step objects with selector and text.

recording_steps[]

Type: object[]

Required: no

Notes: Shadow recording step objects including action, selector, label, and attachment links.

attachments

Type: not_embedded

Required: n/a

Notes: Attachments are fetched separately via the attachments endpoints and are not embedded in GetContent.

video_fields

Type: not_separate

Required: n/a

Notes: Video uses type=video, but the current external JSON does not expose a dedicated video-specific sub-object.

GET

/workspaces/{workspaceId}/content/{contentId}

Fetch a single content item.

Scope: read_content

Summary

Fetch a single content item.

Response fields

id

Type: string

Required: yes

Notes: Content identifier.

workspace_id

Type: string

Required: yes

Notes: Owning workspace.

type

Type: string

Required: yes

Notes: Content type such as note, sop, decision, update, guide, video, or shadow_recording.

title

Type: string

Required: yes

Notes: Content title.

body

Type: string

Required: yes

Notes: Primary body text for the content item.

status

Type: string

Required: yes

Notes: draft, published, archived, or verified lifecycle state.

tags

Type: string[]

Required: no

Notes: Current tag set.

created_by

Type: string

Required: yes

Notes: User who created the content.

updated_by

Type: string

Required: yes

Notes: User who last updated the content.

created_at

Type: string

Required: yes

Notes: RFC3339 creation timestamp.

updated_at

Type: string

Required: yes

Notes: RFC3339 timestamp.

version

Type: number

Required: yes

Notes: Optimistic version counter.

verification_state

Type: string

Required: yes

Notes: verified or needs_review.

owner_user_id

Type: string

Required: yes

Notes: Current content owner ID, may be empty.

owner_name

Type: string

Required: no

Notes: Owner display name when cached.

owner_email

Type: string

Required: no

Notes: Owner email when cached.

timezone

Type: string

Required: yes

Notes: Workspace timezone.

is_pinned

Type: boolean

Required: yes

Notes: Pinned content is surfaced first in listings.

review_interval_days

Type: number

Required: no

Notes: Review cadence when configured.

last_verified_at

Type: string

Required: no

Notes: RFC3339 timestamp for the last verification event.

next_review_at

Type: string

Required: no

Notes: RFC3339 timestamp for the next review due date.

decision_summary

Type: string

Required: no

Notes: Decision-specific summary field when relevant.

decision_date

Type: string

Required: no

Notes: Decision date when present.

sop_steps

Type: string

Required: no

Notes: SOP steps text when relevant.

guide_steps[]

Type: object[]

Required: no

Notes: Guide step objects with selector and text.

recording_steps[]

Type: object[]

Required: no

Notes: Shadow recording step objects including action, selector, label, and attachment links.

attachments

Type: not_embedded

Required: n/a

Notes: Attachments are fetched separately via the attachments endpoints and are not embedded in GetContent.

video_fields

Type: not_separate

Required: n/a

Notes: Video uses type=video, but the current external JSON does not expose a dedicated video-specific sub-object.

Notes

  • Attachments are not embedded here; fetch them through the attachments endpoints, typically filtered by content_id.
  • Content type-specific fields are included only when relevant, for example decision_summary, sop_steps, guide_steps, or recording_steps.
  • Video currently uses type=video, but this external payload does not expose a separate video-specific sub-object.
  • Workspace path params always scope nested resources to a single workspace boundary.
PATCH

/workspaces/{workspaceId}/content/{contentId}

Update a content item.

Scope: write_content

Summary

Update a content item.

Request fields

title

Type: string

Required: yes

Notes: Updated content title.

body

Type: string

Required: yes

Notes: Updated content body. Publish checks still validate length and quality.

tags

Type: string[]

Required: no

Notes: Updated optional tags.

Response fields

id

Type: string

Required: yes

Notes: Content identifier.

workspace_id

Type: string

Required: yes

Notes: Owning workspace.

type

Type: string

Required: yes

Notes: Content type such as note, sop, decision, update, guide, video, or shadow_recording.

title

Type: string

Required: yes

Notes: Content title.

body

Type: string

Required: yes

Notes: Primary body text for the content item.

status

Type: string

Required: yes

Notes: draft, published, archived, or verified lifecycle state.

tags

Type: string[]

Required: no

Notes: Current tag set.

created_by

Type: string

Required: yes

Notes: User who created the content.

updated_by

Type: string

Required: yes

Notes: User who last updated the content.

created_at

Type: string

Required: yes

Notes: RFC3339 creation timestamp.

updated_at

Type: string

Required: yes

Notes: RFC3339 timestamp.

version

Type: number

Required: yes

Notes: Optimistic version counter.

verification_state

Type: string

Required: yes

Notes: verified or needs_review.

owner_user_id

Type: string

Required: yes

Notes: Current content owner ID, may be empty.

owner_name

Type: string

Required: no

Notes: Owner display name when cached.

owner_email

Type: string

Required: no

Notes: Owner email when cached.

timezone

Type: string

Required: yes

Notes: Workspace timezone.

is_pinned

Type: boolean

Required: yes

Notes: Pinned content is surfaced first in listings.

review_interval_days

Type: number

Required: no

Notes: Review cadence when configured.

last_verified_at

Type: string

Required: no

Notes: RFC3339 timestamp for the last verification event.

next_review_at

Type: string

Required: no

Notes: RFC3339 timestamp for the next review due date.

decision_summary

Type: string

Required: no

Notes: Decision-specific summary field when relevant.

decision_date

Type: string

Required: no

Notes: Decision date when present.

sop_steps

Type: string

Required: no

Notes: SOP steps text when relevant.

guide_steps[]

Type: object[]

Required: no

Notes: Guide step objects with selector and text.

recording_steps[]

Type: object[]

Required: no

Notes: Shadow recording step objects including action, selector, label, and attachment links.

attachments

Type: not_embedded

Required: n/a

Notes: Attachments are fetched separately via the attachments endpoints and are not embedded in GetContent.

video_fields

Type: not_separate

Required: n/a

Notes: Video uses type=video, but the current external JSON does not expose a dedicated video-specific sub-object.

Notes

  • Attachments are not embedded here; fetch them through the attachments endpoints, typically filtered by content_id.
  • Content type-specific fields are included only when relevant, for example decision_summary, sop_steps, guide_steps, or recording_steps.
  • Video currently uses type=video, but this external payload does not expose a separate video-specific sub-object.
DELETE

/workspaces/{workspaceId}/content/{contentId}

Delete a content item.

Scope: delete_content

Summary

Delete a content item.

Response fields

data.success

Type: boolean

Required: yes

Notes: Mutation result for delete or revoke style operations.

Notes

  • Attachments are not embedded here; fetch them through the attachments endpoints, typically filtered by content_id.
  • Content type-specific fields are included only when relevant, for example decision_summary, sop_steps, guide_steps, or recording_steps.
  • Video currently uses type=video, but this external payload does not expose a separate video-specific sub-object.
POST

/workspaces/{workspaceId}/content/{contentId}/publish

Publish content after quality validation.

Scope: write_content

Summary

Publish content after quality validation.

Response fields

id

Type: string

Required: yes

Notes: Content identifier.

workspace_id

Type: string

Required: yes

Notes: Owning workspace.

type

Type: string

Required: yes

Notes: Content type such as note, sop, decision, update, guide, video, or shadow_recording.

title

Type: string

Required: yes

Notes: Content title.

body

Type: string

Required: yes

Notes: Primary body text for the content item.

status

Type: string

Required: yes

Notes: draft, published, archived, or verified lifecycle state.

tags

Type: string[]

Required: no

Notes: Current tag set.

created_by

Type: string

Required: yes

Notes: User who created the content.

updated_by

Type: string

Required: yes

Notes: User who last updated the content.

created_at

Type: string

Required: yes

Notes: RFC3339 creation timestamp.

updated_at

Type: string

Required: yes

Notes: RFC3339 timestamp.

version

Type: number

Required: yes

Notes: Optimistic version counter.

verification_state

Type: string

Required: yes

Notes: verified or needs_review.

owner_user_id

Type: string

Required: yes

Notes: Current content owner ID, may be empty.

owner_name

Type: string

Required: no

Notes: Owner display name when cached.

owner_email

Type: string

Required: no

Notes: Owner email when cached.

timezone

Type: string

Required: yes

Notes: Workspace timezone.

is_pinned

Type: boolean

Required: yes

Notes: Pinned content is surfaced first in listings.

review_interval_days

Type: number

Required: no

Notes: Review cadence when configured.

last_verified_at

Type: string

Required: no

Notes: RFC3339 timestamp for the last verification event.

next_review_at

Type: string

Required: no

Notes: RFC3339 timestamp for the next review due date.

decision_summary

Type: string

Required: no

Notes: Decision-specific summary field when relevant.

decision_date

Type: string

Required: no

Notes: Decision date when present.

sop_steps

Type: string

Required: no

Notes: SOP steps text when relevant.

guide_steps[]

Type: object[]

Required: no

Notes: Guide step objects with selector and text.

recording_steps[]

Type: object[]

Required: no

Notes: Shadow recording step objects including action, selector, label, and attachment links.

attachments

Type: not_embedded

Required: n/a

Notes: Attachments are fetched separately via the attachments endpoints and are not embedded in GetContent.

video_fields

Type: not_separate

Required: n/a

Notes: Video uses type=video, but the current external JSON does not expose a dedicated video-specific sub-object.

Notes

  • Publish validates content quality before allowing the status transition.
POST

/workspaces/{workspaceId}/content/{contentId}/archive

Archive content.

Scope: write_content

Summary

Archive content.

Response fields

id

Type: string

Required: yes

Notes: Content identifier.

workspace_id

Type: string

Required: yes

Notes: Owning workspace.

type

Type: string

Required: yes

Notes: Content type such as note, sop, decision, update, guide, video, or shadow_recording.

title

Type: string

Required: yes

Notes: Content title.

body

Type: string

Required: yes

Notes: Primary body text for the content item.

status

Type: string

Required: yes

Notes: draft, published, archived, or verified lifecycle state.

tags

Type: string[]

Required: no

Notes: Current tag set.

created_by

Type: string

Required: yes

Notes: User who created the content.

updated_by

Type: string

Required: yes

Notes: User who last updated the content.

created_at

Type: string

Required: yes

Notes: RFC3339 creation timestamp.

updated_at

Type: string

Required: yes

Notes: RFC3339 timestamp.

version

Type: number

Required: yes

Notes: Optimistic version counter.

verification_state

Type: string

Required: yes

Notes: verified or needs_review.

owner_user_id

Type: string

Required: yes

Notes: Current content owner ID, may be empty.

owner_name

Type: string

Required: no

Notes: Owner display name when cached.

owner_email

Type: string

Required: no

Notes: Owner email when cached.

timezone

Type: string

Required: yes

Notes: Workspace timezone.

is_pinned

Type: boolean

Required: yes

Notes: Pinned content is surfaced first in listings.

review_interval_days

Type: number

Required: no

Notes: Review cadence when configured.

last_verified_at

Type: string

Required: no

Notes: RFC3339 timestamp for the last verification event.

next_review_at

Type: string

Required: no

Notes: RFC3339 timestamp for the next review due date.

decision_summary

Type: string

Required: no

Notes: Decision-specific summary field when relevant.

decision_date

Type: string

Required: no

Notes: Decision date when present.

sop_steps

Type: string

Required: no

Notes: SOP steps text when relevant.

guide_steps[]

Type: object[]

Required: no

Notes: Guide step objects with selector and text.

recording_steps[]

Type: object[]

Required: no

Notes: Shadow recording step objects including action, selector, label, and attachment links.

attachments

Type: not_embedded

Required: n/a

Notes: Attachments are fetched separately via the attachments endpoints and are not embedded in GetContent.

video_fields

Type: not_separate

Required: n/a

Notes: Video uses type=video, but the current external JSON does not expose a dedicated video-specific sub-object.

POST

/workspaces/{workspaceId}/content/{contentId}/restore

Restore archived content.

Scope: write_content

Summary

Restore archived content.

Response fields

id

Type: string

Required: yes

Notes: Content identifier.

workspace_id

Type: string

Required: yes

Notes: Owning workspace.

type

Type: string

Required: yes

Notes: Content type such as note, sop, decision, update, guide, video, or shadow_recording.

title

Type: string

Required: yes

Notes: Content title.

body

Type: string

Required: yes

Notes: Primary body text for the content item.

status

Type: string

Required: yes

Notes: draft, published, archived, or verified lifecycle state.

tags

Type: string[]

Required: no

Notes: Current tag set.

created_by

Type: string

Required: yes

Notes: User who created the content.

updated_by

Type: string

Required: yes

Notes: User who last updated the content.

created_at

Type: string

Required: yes

Notes: RFC3339 creation timestamp.

updated_at

Type: string

Required: yes

Notes: RFC3339 timestamp.

version

Type: number

Required: yes

Notes: Optimistic version counter.

verification_state

Type: string

Required: yes

Notes: verified or needs_review.

owner_user_id

Type: string

Required: yes

Notes: Current content owner ID, may be empty.

owner_name

Type: string

Required: no

Notes: Owner display name when cached.

owner_email

Type: string

Required: no

Notes: Owner email when cached.

timezone

Type: string

Required: yes

Notes: Workspace timezone.

is_pinned

Type: boolean

Required: yes

Notes: Pinned content is surfaced first in listings.

review_interval_days

Type: number

Required: no

Notes: Review cadence when configured.

last_verified_at

Type: string

Required: no

Notes: RFC3339 timestamp for the last verification event.

next_review_at

Type: string

Required: no

Notes: RFC3339 timestamp for the next review due date.

decision_summary

Type: string

Required: no

Notes: Decision-specific summary field when relevant.

decision_date

Type: string

Required: no

Notes: Decision date when present.

sop_steps

Type: string

Required: no

Notes: SOP steps text when relevant.

guide_steps[]

Type: object[]

Required: no

Notes: Guide step objects with selector and text.

recording_steps[]

Type: object[]

Required: no

Notes: Shadow recording step objects including action, selector, label, and attachment links.

attachments

Type: not_embedded

Required: n/a

Notes: Attachments are fetched separately via the attachments endpoints and are not embedded in GetContent.

video_fields

Type: not_separate

Required: n/a

Notes: Video uses type=video, but the current external JSON does not expose a dedicated video-specific sub-object.

POST

/workspaces/{workspaceId}/content/{contentId}/verify

Mark content as verified.

Scope: write_content

Summary

Mark content as verified.

Response fields

id

Type: string

Required: yes

Notes: Content identifier.

workspace_id

Type: string

Required: yes

Notes: Owning workspace.

type

Type: string

Required: yes

Notes: Content type such as note, sop, decision, update, guide, video, or shadow_recording.

title

Type: string

Required: yes

Notes: Content title.

body

Type: string

Required: yes

Notes: Primary body text for the content item.

status

Type: string

Required: yes

Notes: draft, published, archived, or verified lifecycle state.

tags

Type: string[]

Required: no

Notes: Current tag set.

created_by

Type: string

Required: yes

Notes: User who created the content.

updated_by

Type: string

Required: yes

Notes: User who last updated the content.

created_at

Type: string

Required: yes

Notes: RFC3339 creation timestamp.

updated_at

Type: string

Required: yes

Notes: RFC3339 timestamp.

version

Type: number

Required: yes

Notes: Optimistic version counter.

verification_state

Type: string

Required: yes

Notes: verified or needs_review.

owner_user_id

Type: string

Required: yes

Notes: Current content owner ID, may be empty.

owner_name

Type: string

Required: no

Notes: Owner display name when cached.

owner_email

Type: string

Required: no

Notes: Owner email when cached.

timezone

Type: string

Required: yes

Notes: Workspace timezone.

is_pinned

Type: boolean

Required: yes

Notes: Pinned content is surfaced first in listings.

review_interval_days

Type: number

Required: no

Notes: Review cadence when configured.

last_verified_at

Type: string

Required: no

Notes: RFC3339 timestamp for the last verification event.

next_review_at

Type: string

Required: no

Notes: RFC3339 timestamp for the next review due date.

decision_summary

Type: string

Required: no

Notes: Decision-specific summary field when relevant.

decision_date

Type: string

Required: no

Notes: Decision date when present.

sop_steps

Type: string

Required: no

Notes: SOP steps text when relevant.

guide_steps[]

Type: object[]

Required: no

Notes: Guide step objects with selector and text.

recording_steps[]

Type: object[]

Required: no

Notes: Shadow recording step objects including action, selector, label, and attachment links.

attachments

Type: not_embedded

Required: n/a

Notes: Attachments are fetched separately via the attachments endpoints and are not embedded in GetContent.

video_fields

Type: not_separate

Required: n/a

Notes: Video uses type=video, but the current external JSON does not expose a dedicated video-specific sub-object.

GET

/workspaces/{workspaceId}/content/tags

List known tags in the workspace.

Scope: read_content

Summary

List known tags in the workspace.

Response fields

data[]

Type: string[]

Required: yes

Notes: Known content tags in the workspace.

Notes

  • Workspace path params always scope nested resources to a single workspace boundary.
GET

/workspaces/{workspaceId}/content/needs-review

List content due for review.

Scope: read_content

Summary

List content due for review.

Request fields

page

Type: number

Required: no

Notes: 1-based page number. Defaults to 1.

page_size

Type: number

Required: no

Notes: Items per page. Defaults to 20 unless noted otherwise on the route.

Response fields

data[]

Type: Content[]

Required: yes

Notes: List of content envelopes for the workspace.

meta.total

Type: number

Required: yes

Notes: Total records available for pagination.

meta.page

Type: number

Required: yes

Notes: Current 1-based page number.

meta.page_size

Type: number

Required: yes

Notes: Page size applied to this response.

meta.total_pages

Type: number

Required: yes

Notes: Total number of pages for the current filter set.

Referenced type fields

Content fields

id

Type: string

Required: yes

Notes: Content identifier.

workspace_id

Type: string

Required: yes

Notes: Owning workspace.

type

Type: string

Required: yes

Notes: Content type such as note, sop, decision, update, guide, video, or shadow_recording.

title

Type: string

Required: yes

Notes: Content title.

body

Type: string

Required: yes

Notes: Primary body text for the content item.

status

Type: string

Required: yes

Notes: draft, published, archived, or verified lifecycle state.

tags

Type: string[]

Required: no

Notes: Current tag set.

created_by

Type: string

Required: yes

Notes: User who created the content.

updated_by

Type: string

Required: yes

Notes: User who last updated the content.

created_at

Type: string

Required: yes

Notes: RFC3339 creation timestamp.

updated_at

Type: string

Required: yes

Notes: RFC3339 timestamp.

version

Type: number

Required: yes

Notes: Optimistic version counter.

verification_state

Type: string

Required: yes

Notes: verified or needs_review.

owner_user_id

Type: string

Required: yes

Notes: Current content owner ID, may be empty.

owner_name

Type: string

Required: no

Notes: Owner display name when cached.

owner_email

Type: string

Required: no

Notes: Owner email when cached.

timezone

Type: string

Required: yes

Notes: Workspace timezone.

is_pinned

Type: boolean

Required: yes

Notes: Pinned content is surfaced first in listings.

review_interval_days

Type: number

Required: no

Notes: Review cadence when configured.

last_verified_at

Type: string

Required: no

Notes: RFC3339 timestamp for the last verification event.

next_review_at

Type: string

Required: no

Notes: RFC3339 timestamp for the next review due date.

decision_summary

Type: string

Required: no

Notes: Decision-specific summary field when relevant.

decision_date

Type: string

Required: no

Notes: Decision date when present.

sop_steps

Type: string

Required: no

Notes: SOP steps text when relevant.

guide_steps[]

Type: object[]

Required: no

Notes: Guide step objects with selector and text.

recording_steps[]

Type: object[]

Required: no

Notes: Shadow recording step objects including action, selector, label, and attachment links.

attachments

Type: not_embedded

Required: n/a

Notes: Attachments are fetched separately via the attachments endpoints and are not embedded in GetContent.

video_fields

Type: not_separate

Required: n/a

Notes: Video uses type=video, but the current external JSON does not expose a dedicated video-specific sub-object.

Notes

  • Workspace path params always scope nested resources to a single workspace boundary.
GET

/workspaces/{workspaceId}/content/needs-review/count

Return a compact count of content due for review.

Scope: read_content

Summary

Return a compact count of content due for review.

Response fields

data.count

Type: number

Required: yes

Notes: Compact count value for dashboard-style summaries.

Notes

  • Workspace path params always scope nested resources to a single workspace boundary.

Attachments

Upload files, inspect metadata, and download or delete attachments tied to content.

5 routes
GET

/workspaces/{workspaceId}/attachments

List attachments for the workspace or a content item.

Scope: read_content

Summary

List attachments for the workspace or a content item.

Request fields

page

Type: number

Required: no

Notes: 1-based page number. Defaults to 1.

page_size

Type: number

Required: no

Notes: Items per page. Defaults to 100 for attachments.

content_id

Type: string

Required: no

Notes: Optional filter to return only attachments linked to one content item.

Response fields

data[]

Type: Attachment[]

Required: yes

Notes: Attachment list for the workspace.

meta.total

Type: number

Required: yes

Notes: Total matching attachments.

meta.page

Type: number

Required: yes

Notes: Current 1-based page number.

meta.page_size

Type: number

Required: yes

Notes: Page size applied to this response.

meta.total_pages

Type: number

Required: yes

Notes: Total available pages.

Referenced type fields

Attachment fields

id

Type: string

Required: yes

Notes: Attachment identifier.

filename

Type: string

Required: yes

Notes: Stored filename.

mime_type

Type: string

Required: yes

Notes: Stored content type.

content_id

Type: string

Required: no

Notes: Linked content when present.

size_bytes

Type: number

Required: yes

Notes: Stored object size.

Notes

  • Workspace path params always scope nested resources to a single workspace boundary.
POST

/workspaces/{workspaceId}/attachments

Upload a multipart attachment.

Scope: write_content

Summary

Upload a multipart attachment.

Request fields

filename

Type: string

Required: yes

Notes: Original or display filename.

mime_type

Type: string

Required: yes

Notes: Content type for storage and download headers.

content_id

Type: string

Required: no

Notes: Associate the attachment with a content record.

data

Type: binary

Required: yes

Notes: Multipart file payload.

Response fields

id

Type: string

Required: yes

Notes: Attachment identifier.

filename

Type: string

Required: yes

Notes: Stored filename.

mime_type

Type: string

Required: yes

Notes: Stored content type.

content_id

Type: string

Required: no

Notes: Linked content when present.

size_bytes

Type: number

Required: yes

Notes: Stored object size.

Notes

  • This route expects multipart form data, not JSON.
GET

/workspaces/{workspaceId}/attachments/{attachmentId}

Return one attachment metadata record.

Scope: read_content

Summary

Return one attachment metadata record.

Response fields

id

Type: string

Required: yes

Notes: Attachment identifier.

filename

Type: string

Required: yes

Notes: Stored filename.

mime_type

Type: string

Required: yes

Notes: Stored content type.

content_id

Type: string

Required: no

Notes: Linked content when present.

size_bytes

Type: number

Required: yes

Notes: Stored object size.

Notes

  • Workspace path params always scope nested resources to a single workspace boundary.
GET

/workspaces/{workspaceId}/attachments/{attachmentId}/download

Download the attachment binary payload.

Scope: read_content

Summary

Download the attachment binary payload.

Response fields

body

Type: binary

Required: yes

Notes: Raw file payload returned by the download route.

content-type

Type: header

Required: yes

Notes: Download response MIME type.

Notes

  • Workspace path params always scope nested resources to a single workspace boundary.
DELETE

/workspaces/{workspaceId}/attachments/{attachmentId}

Delete an attachment.

Scope: write_content

Summary

Delete an attachment.

Response fields

data.success

Type: boolean

Required: yes

Notes: Mutation result for delete or revoke style operations.

Matching Rules

Define URL matching rules that attach content to real product pages.

5 routes
GET

/workspaces/{workspaceId}/matching-rules

List matching rules.

Scope: read_content

Summary

List matching rules.

Request fields

page

Type: number

Required: no

Notes: 1-based page number. Defaults to 1.

page_size

Type: number

Required: no

Notes: Items per page. Defaults to 20 unless noted otherwise on the route.

Response fields

data[]

Type: MatchingRule[]

Required: yes

Notes: Matching rules list.

meta.total

Type: number

Required: yes

Notes: Total matching rules.

meta.page

Type: number

Required: yes

Notes: Current 1-based page number.

meta.page_size

Type: number

Required: yes

Notes: Page size applied to this response.

meta.total_pages

Type: number

Required: yes

Notes: Total available pages.

Referenced type fields

MatchingRule fields

id

Type: string

Required: yes

Notes: Rule identifier.

workspace_id

Type: string

Required: yes

Notes: Owning workspace.

content_ids

Type: string[]

Required: yes

Notes: Referenced content records.

priority

Type: number

Required: yes

Notes: Resolved priority after defaults.

Notes

  • Workspace path params always scope nested resources to a single workspace boundary.
POST

/workspaces/{workspaceId}/matching-rules

Create a new matching rule.

Scope: write_content

Summary

Create a new matching rule.

Request fields

pattern

Type: string

Required: yes

Notes: URL pattern to match.

match_type

Type: string

Required: yes

Notes: Match strategy such as prefix or exact.

content_ids

Type: string[]

Required: yes

Notes: Content records activated by this rule.

priority

Type: number

Required: no

Notes: Higher values win when multiple rules match.

Response fields

id

Type: string

Required: yes

Notes: Rule identifier.

workspace_id

Type: string

Required: yes

Notes: Owning workspace.

content_ids

Type: string[]

Required: yes

Notes: Referenced content records.

priority

Type: number

Required: yes

Notes: Resolved priority after defaults.

GET

/workspaces/{workspaceId}/matching-rules/{ruleId}

Fetch one matching rule.

Scope: read_content

Summary

Fetch one matching rule.

Response fields

id

Type: string

Required: yes

Notes: Rule identifier.

workspace_id

Type: string

Required: yes

Notes: Owning workspace.

content_ids

Type: string[]

Required: yes

Notes: Referenced content records.

priority

Type: number

Required: yes

Notes: Resolved priority after defaults.

Notes

  • Workspace path params always scope nested resources to a single workspace boundary.
PATCH

/workspaces/{workspaceId}/matching-rules/{ruleId}

Update a matching rule.

Scope: write_content

Summary

Update a matching rule.

Request fields

pattern

Type: string

Required: yes

Notes: URL pattern to match.

match_type

Type: string

Required: yes

Notes: Match strategy such as prefix or exact.

content_ids

Type: string[]

Required: yes

Notes: Content records activated by this rule.

priority

Type: number

Required: no

Notes: Higher values win when multiple rules match.

Response fields

id

Type: string

Required: yes

Notes: Rule identifier.

workspace_id

Type: string

Required: yes

Notes: Owning workspace.

content_ids

Type: string[]

Required: yes

Notes: Referenced content records.

priority

Type: number

Required: yes

Notes: Resolved priority after defaults.

DELETE

/workspaces/{workspaceId}/matching-rules/{ruleId}

Delete a matching rule.

Scope: write_content

Summary

Delete a matching rule.

Response fields

data.success

Type: boolean

Required: yes

Notes: Mutation result for delete or revoke style operations.

Audit & Webhooks

Export audit history and manage outbound event subscriptions.

8 routes
GET

/workspaces/{workspaceId}/audit-events

List audit events with filters and pagination.

Scope: read_content

Summary

List audit events with filters and pagination.

Request fields

page

Type: number

Required: no

Notes: 1-based page number. Defaults to 1.

page_size

Type: number

Required: no

Notes: Items per page. Defaults to 20 unless noted otherwise on the route.

event_type

Type: string

Required: no

Notes: Optional audit event type filter.

entity_type

Type: string

Required: no

Notes: Optional entity type filter.

user_id

Type: string

Required: no

Notes: Optional actor filter.

search

Type: string

Required: no

Notes: Optional text search filter.

from

Type: string

Required: no

Notes: RFC3339 lower bound timestamp.

to

Type: string

Required: no

Notes: RFC3339 upper bound timestamp.

Response fields

data[]

Type: AuditEvent[]

Required: yes

Notes: Workspace audit events for the requested filter window.

meta.total

Type: number

Required: yes

Notes: Total records available for pagination.

meta.page

Type: number

Required: yes

Notes: Current 1-based page number.

meta.page_size

Type: number

Required: yes

Notes: Page size applied to this response.

meta.total_pages

Type: number

Required: yes

Notes: Total number of pages for the current filter set.

Referenced type fields

AuditEvent fields

id

Type: string

Required: yes

Notes: Audit event identifier.

event_type

Type: string

Required: yes

Notes: Action name such as content.created or content.updated.

entity_type

Type: string

Required: yes

Notes: Entity category affected by the action.

entity_id

Type: string

Required: no

Notes: Identifier of the entity when available.

created_at

Type: string

Required: yes

Notes: RFC3339 timestamp.

Notes

  • Workspace path params always scope nested resources to a single workspace boundary.
GET

/workspaces/{workspaceId}/webhooks

List webhook subscriptions.

Scope: read_content

Summary

List webhook subscriptions.

Request fields

page

Type: number

Required: no

Notes: 1-based page number. Defaults to 1.

page_size

Type: number

Required: no

Notes: Items per page. Defaults to 20 unless noted otherwise on the route.

Response fields

data[]

Type: Webhook[]

Required: yes

Notes: Webhook subscriptions list.

meta.total

Type: number

Required: yes

Notes: Total webhook subscriptions.

meta.page

Type: number

Required: yes

Notes: Current 1-based page number.

meta.page_size

Type: number

Required: yes

Notes: Page size applied to this response.

meta.total_pages

Type: number

Required: yes

Notes: Total available pages.

Referenced type fields

Webhook fields

id

Type: string

Required: yes

Notes: Webhook identifier.

target_url

Type: string

Required: yes

Notes: Stored destination URL.

event_types

Type: string[]

Required: yes

Notes: Current subscription list.

active

Type: boolean

Required: yes

Notes: Current delivery state.

WebhookHeaders fields

Content-Type

Type: header

Required: yes

Notes: Always application/json.

X-ContextPilot-Event

Type: header

Required: yes

Notes: Same normalized value as payload.event.

X-ContextPilot-Signature

Type: header

Required: yes

Notes: HMAC SHA256 signature in the form sha256=<digest>.

X-ContextPilot-Webhook-Id

Type: header

Required: yes

Notes: Webhook subscription identifier.

X-ContextPilot-Event-Id

Type: header

Required: yes

Notes: Same value as payload.event_id for production deliveries; empty for webhook.test.

WebhookEventPayload fields

event

Type: string

Required: yes

Notes: Normalized event name, such as content.created or content.verified.

event_id

Type: string

Required: yes

Notes: Unique event envelope identifier used for tracing and deduplication.

workspace_id

Type: string

Required: yes

Notes: Workspace that emitted the event.

occurred_at

Type: string

Required: yes

Notes: RFC3339 timestamp for the original domain event.

source_service

Type: string

Required: yes

Notes: Originating internal service, currently content.

data

Type: WebhookEventData

Required: yes

Notes: Event-specific payload fields. Shape depends on the event type.

WebhookEventData fields

content_id

Type: string

Required: yes

Notes: Content identifier for all currently supported automatic webhook events.

workspace_id

Type: string

Required: yes

Notes: Repeated inside event data for easier consumer-side routing.

type

Type: string

Required: conditional

Notes: Content type, included on content.created.

title

Type: string

Required: conditional

Notes: Content title, included on content.created.

created_by

Type: string

Required: conditional

Notes: User who created the content.

created_at

Type: string

Required: conditional

Notes: RFC3339 timestamp for creation.

updated_by

Type: string

Required: conditional

Notes: User who updated the content.

updated_at

Type: string

Required: conditional

Notes: RFC3339 timestamp for update.

deleted_by

Type: string

Required: conditional

Notes: User who deleted the content.

deleted_at

Type: string

Required: conditional

Notes: RFC3339 timestamp for delete.

published_by

Type: string

Required: conditional

Notes: User who published the content.

published_at

Type: string

Required: conditional

Notes: RFC3339 timestamp for publish.

archived_by

Type: string

Required: conditional

Notes: User who archived the content.

archived_at

Type: string

Required: conditional

Notes: RFC3339 timestamp for archive.

restored_by

Type: string

Required: conditional

Notes: User who restored the content.

restored_at

Type: string

Required: conditional

Notes: RFC3339 timestamp for restore.

verified_by

Type: string

Required: conditional

Notes: User who marked the content verified.

verified_at

Type: string

Required: conditional

Notes: RFC3339 timestamp for verify.

source

Type: string

Required: conditional

Notes: Original content source when present.

page_host

Type: string

Required: conditional

Notes: Associated page host when available.

page_path

Type: string

Required: conditional

Notes: Associated page path when available.

company_id

Type: string

Required: conditional

Notes: Company identifier, currently included on content.created.

fields_changed

Type: string[]

Required: conditional

Notes: Field list included on content.updated.

old_status

Type: string

Required: conditional

Notes: Previous status on updated, published, archived, and restored events.

new_status

Type: string

Required: conditional

Notes: New status included on content.updated.

review_interval_days

Type: number

Required: conditional

Notes: Review cadence included on content.verified.

note

Type: string

Required: conditional

Notes: Verification note included on content.verified.

owner_user_id

Type: string

Required: conditional

Notes: Assigned owner for content.verified.

content_title

Type: string

Required: conditional

Notes: Title snapshot included on content.verified.

next_review_at

Type: string

Required: conditional

Notes: Next scheduled review timestamp when available.

recording_steps[]

Type: object[]

Required: conditional

Notes: Structured recording steps included on content.created when the source provides them.

Production delivery payload examplecurl / json
{
  "event": "content.updated",
  "event_id": "evt_01JX9ZK1M9N8",
  "workspace_id": "ws_123",
  "occurred_at": "2026-02-28T14:22:11Z",
  "source_service": "content",
  "data": {
    "content_id": "cnt_123",
    "workspace_id": "ws_123",
    "updated_by": "usr_42",
    "updated_at": "2026-02-28T14:22:11Z",
    "source": "extension",
    "page_host": "app.example.com",
    "page_path": "/refunds/partial",
    "fields_changed": ["title", "body", "tags"],
    "old_status": "draft",
    "new_status": "draft"
  }
}

Notes

  • Webhook subscriptions are persisted and automatic delivery is active for content events.
  • Supported automatic event types are content.created, content.updated, content.deleted, content.published, content.archived, content.restored, and content.verified.
  • Workspace path params always scope nested resources to a single workspace boundary.
POST

/workspaces/{workspaceId}/webhooks

Create a webhook subscription.

Scope: write_content

Summary

Create a webhook subscription.

Request fields

target_url

Type: string

Required: yes

Notes: Public HTTPS endpoint only.

event_types

Type: string[]

Required: yes

Notes: Subscribed event list, such as content.created.

active

Type: boolean

Required: yes

Notes: Whether deliveries are enabled.

Response fields

id

Type: string

Required: yes

Notes: Webhook identifier.

target_url

Type: string

Required: yes

Notes: Stored destination URL.

event_types

Type: string[]

Required: yes

Notes: Current subscription list.

active

Type: boolean

Required: yes

Notes: Current delivery state.

Referenced type fields

WebhookHeaders fields

Content-Type

Type: header

Required: yes

Notes: Always application/json.

X-ContextPilot-Event

Type: header

Required: yes

Notes: Same normalized value as payload.event.

X-ContextPilot-Signature

Type: header

Required: yes

Notes: HMAC SHA256 signature in the form sha256=<digest>.

X-ContextPilot-Webhook-Id

Type: header

Required: yes

Notes: Webhook subscription identifier.

X-ContextPilot-Event-Id

Type: header

Required: yes

Notes: Same value as payload.event_id for production deliveries; empty for webhook.test.

WebhookEventPayload fields

event

Type: string

Required: yes

Notes: Normalized event name, such as content.created or content.verified.

event_id

Type: string

Required: yes

Notes: Unique event envelope identifier used for tracing and deduplication.

workspace_id

Type: string

Required: yes

Notes: Workspace that emitted the event.

occurred_at

Type: string

Required: yes

Notes: RFC3339 timestamp for the original domain event.

source_service

Type: string

Required: yes

Notes: Originating internal service, currently content.

data

Type: WebhookEventData

Required: yes

Notes: Event-specific payload fields. Shape depends on the event type.

WebhookEventData fields

content_id

Type: string

Required: yes

Notes: Content identifier for all currently supported automatic webhook events.

workspace_id

Type: string

Required: yes

Notes: Repeated inside event data for easier consumer-side routing.

type

Type: string

Required: conditional

Notes: Content type, included on content.created.

title

Type: string

Required: conditional

Notes: Content title, included on content.created.

created_by

Type: string

Required: conditional

Notes: User who created the content.

created_at

Type: string

Required: conditional

Notes: RFC3339 timestamp for creation.

updated_by

Type: string

Required: conditional

Notes: User who updated the content.

updated_at

Type: string

Required: conditional

Notes: RFC3339 timestamp for update.

deleted_by

Type: string

Required: conditional

Notes: User who deleted the content.

deleted_at

Type: string

Required: conditional

Notes: RFC3339 timestamp for delete.

published_by

Type: string

Required: conditional

Notes: User who published the content.

published_at

Type: string

Required: conditional

Notes: RFC3339 timestamp for publish.

archived_by

Type: string

Required: conditional

Notes: User who archived the content.

archived_at

Type: string

Required: conditional

Notes: RFC3339 timestamp for archive.

restored_by

Type: string

Required: conditional

Notes: User who restored the content.

restored_at

Type: string

Required: conditional

Notes: RFC3339 timestamp for restore.

verified_by

Type: string

Required: conditional

Notes: User who marked the content verified.

verified_at

Type: string

Required: conditional

Notes: RFC3339 timestamp for verify.

source

Type: string

Required: conditional

Notes: Original content source when present.

page_host

Type: string

Required: conditional

Notes: Associated page host when available.

page_path

Type: string

Required: conditional

Notes: Associated page path when available.

company_id

Type: string

Required: conditional

Notes: Company identifier, currently included on content.created.

fields_changed

Type: string[]

Required: conditional

Notes: Field list included on content.updated.

old_status

Type: string

Required: conditional

Notes: Previous status on updated, published, archived, and restored events.

new_status

Type: string

Required: conditional

Notes: New status included on content.updated.

review_interval_days

Type: number

Required: conditional

Notes: Review cadence included on content.verified.

note

Type: string

Required: conditional

Notes: Verification note included on content.verified.

owner_user_id

Type: string

Required: conditional

Notes: Assigned owner for content.verified.

content_title

Type: string

Required: conditional

Notes: Title snapshot included on content.verified.

next_review_at

Type: string

Required: conditional

Notes: Next scheduled review timestamp when available.

recording_steps[]

Type: object[]

Required: conditional

Notes: Structured recording steps included on content.created when the source provides them.

Production delivery payload examplecurl / json
{
  "event": "content.updated",
  "event_id": "evt_01JX9ZK1M9N8",
  "workspace_id": "ws_123",
  "occurred_at": "2026-02-28T14:22:11Z",
  "source_service": "content",
  "data": {
    "content_id": "cnt_123",
    "workspace_id": "ws_123",
    "updated_by": "usr_42",
    "updated_at": "2026-02-28T14:22:11Z",
    "source": "extension",
    "page_host": "app.example.com",
    "page_path": "/refunds/partial",
    "fields_changed": ["title", "body", "tags"],
    "old_status": "draft",
    "new_status": "draft"
  }
}

Notes

  • Webhook target_url must resolve to a public HTTPS endpoint.
  • Webhook subscriptions are persisted and automatic delivery is active for content events.
  • Supported automatic event types are content.created, content.updated, content.deleted, content.published, content.archived, content.restored, and content.verified.
GET

/workspaces/{workspaceId}/webhooks/{webhookId}

Fetch one webhook subscription.

Scope: read_content

Summary

Fetch one webhook subscription.

Response fields

id

Type: string

Required: yes

Notes: Webhook identifier.

target_url

Type: string

Required: yes

Notes: Stored destination URL.

event_types

Type: string[]

Required: yes

Notes: Current subscription list.

active

Type: boolean

Required: yes

Notes: Current delivery state.

Referenced type fields

WebhookHeaders fields

Content-Type

Type: header

Required: yes

Notes: Always application/json.

X-ContextPilot-Event

Type: header

Required: yes

Notes: Same normalized value as payload.event.

X-ContextPilot-Signature

Type: header

Required: yes

Notes: HMAC SHA256 signature in the form sha256=<digest>.

X-ContextPilot-Webhook-Id

Type: header

Required: yes

Notes: Webhook subscription identifier.

X-ContextPilot-Event-Id

Type: header

Required: yes

Notes: Same value as payload.event_id for production deliveries; empty for webhook.test.

WebhookEventPayload fields

event

Type: string

Required: yes

Notes: Normalized event name, such as content.created or content.verified.

event_id

Type: string

Required: yes

Notes: Unique event envelope identifier used for tracing and deduplication.

workspace_id

Type: string

Required: yes

Notes: Workspace that emitted the event.

occurred_at

Type: string

Required: yes

Notes: RFC3339 timestamp for the original domain event.

source_service

Type: string

Required: yes

Notes: Originating internal service, currently content.

data

Type: WebhookEventData

Required: yes

Notes: Event-specific payload fields. Shape depends on the event type.

WebhookEventData fields

content_id

Type: string

Required: yes

Notes: Content identifier for all currently supported automatic webhook events.

workspace_id

Type: string

Required: yes

Notes: Repeated inside event data for easier consumer-side routing.

type

Type: string

Required: conditional

Notes: Content type, included on content.created.

title

Type: string

Required: conditional

Notes: Content title, included on content.created.

created_by

Type: string

Required: conditional

Notes: User who created the content.

created_at

Type: string

Required: conditional

Notes: RFC3339 timestamp for creation.

updated_by

Type: string

Required: conditional

Notes: User who updated the content.

updated_at

Type: string

Required: conditional

Notes: RFC3339 timestamp for update.

deleted_by

Type: string

Required: conditional

Notes: User who deleted the content.

deleted_at

Type: string

Required: conditional

Notes: RFC3339 timestamp for delete.

published_by

Type: string

Required: conditional

Notes: User who published the content.

published_at

Type: string

Required: conditional

Notes: RFC3339 timestamp for publish.

archived_by

Type: string

Required: conditional

Notes: User who archived the content.

archived_at

Type: string

Required: conditional

Notes: RFC3339 timestamp for archive.

restored_by

Type: string

Required: conditional

Notes: User who restored the content.

restored_at

Type: string

Required: conditional

Notes: RFC3339 timestamp for restore.

verified_by

Type: string

Required: conditional

Notes: User who marked the content verified.

verified_at

Type: string

Required: conditional

Notes: RFC3339 timestamp for verify.

source

Type: string

Required: conditional

Notes: Original content source when present.

page_host

Type: string

Required: conditional

Notes: Associated page host when available.

page_path

Type: string

Required: conditional

Notes: Associated page path when available.

company_id

Type: string

Required: conditional

Notes: Company identifier, currently included on content.created.

fields_changed

Type: string[]

Required: conditional

Notes: Field list included on content.updated.

old_status

Type: string

Required: conditional

Notes: Previous status on updated, published, archived, and restored events.

new_status

Type: string

Required: conditional

Notes: New status included on content.updated.

review_interval_days

Type: number

Required: conditional

Notes: Review cadence included on content.verified.

note

Type: string

Required: conditional

Notes: Verification note included on content.verified.

owner_user_id

Type: string

Required: conditional

Notes: Assigned owner for content.verified.

content_title

Type: string

Required: conditional

Notes: Title snapshot included on content.verified.

next_review_at

Type: string

Required: conditional

Notes: Next scheduled review timestamp when available.

recording_steps[]

Type: object[]

Required: conditional

Notes: Structured recording steps included on content.created when the source provides them.

Production delivery payload examplecurl / json
{
  "event": "content.updated",
  "event_id": "evt_01JX9ZK1M9N8",
  "workspace_id": "ws_123",
  "occurred_at": "2026-02-28T14:22:11Z",
  "source_service": "content",
  "data": {
    "content_id": "cnt_123",
    "workspace_id": "ws_123",
    "updated_by": "usr_42",
    "updated_at": "2026-02-28T14:22:11Z",
    "source": "extension",
    "page_host": "app.example.com",
    "page_path": "/refunds/partial",
    "fields_changed": ["title", "body", "tags"],
    "old_status": "draft",
    "new_status": "draft"
  }
}

Notes

  • Webhook subscriptions are persisted and automatic delivery is active for content events.
  • Supported automatic event types are content.created, content.updated, content.deleted, content.published, content.archived, content.restored, and content.verified.
  • Workspace path params always scope nested resources to a single workspace boundary.
PATCH

/workspaces/{workspaceId}/webhooks/{webhookId}

Update target URL, events, or active status.

Scope: write_content

Summary

Update target URL, events, or active status.

Request fields

target_url

Type: string

Required: yes

Notes: Public HTTPS endpoint only.

event_types

Type: string[]

Required: yes

Notes: Subscribed event list, such as content.created.

active

Type: boolean

Required: yes

Notes: Whether deliveries are enabled.

Response fields

id

Type: string

Required: yes

Notes: Webhook identifier.

target_url

Type: string

Required: yes

Notes: Stored destination URL.

event_types

Type: string[]

Required: yes

Notes: Current subscription list.

active

Type: boolean

Required: yes

Notes: Current delivery state.

Referenced type fields

WebhookHeaders fields

Content-Type

Type: header

Required: yes

Notes: Always application/json.

X-ContextPilot-Event

Type: header

Required: yes

Notes: Same normalized value as payload.event.

X-ContextPilot-Signature

Type: header

Required: yes

Notes: HMAC SHA256 signature in the form sha256=<digest>.

X-ContextPilot-Webhook-Id

Type: header

Required: yes

Notes: Webhook subscription identifier.

X-ContextPilot-Event-Id

Type: header

Required: yes

Notes: Same value as payload.event_id for production deliveries; empty for webhook.test.

WebhookEventPayload fields

event

Type: string

Required: yes

Notes: Normalized event name, such as content.created or content.verified.

event_id

Type: string

Required: yes

Notes: Unique event envelope identifier used for tracing and deduplication.

workspace_id

Type: string

Required: yes

Notes: Workspace that emitted the event.

occurred_at

Type: string

Required: yes

Notes: RFC3339 timestamp for the original domain event.

source_service

Type: string

Required: yes

Notes: Originating internal service, currently content.

data

Type: WebhookEventData

Required: yes

Notes: Event-specific payload fields. Shape depends on the event type.

WebhookEventData fields

content_id

Type: string

Required: yes

Notes: Content identifier for all currently supported automatic webhook events.

workspace_id

Type: string

Required: yes

Notes: Repeated inside event data for easier consumer-side routing.

type

Type: string

Required: conditional

Notes: Content type, included on content.created.

title

Type: string

Required: conditional

Notes: Content title, included on content.created.

created_by

Type: string

Required: conditional

Notes: User who created the content.

created_at

Type: string

Required: conditional

Notes: RFC3339 timestamp for creation.

updated_by

Type: string

Required: conditional

Notes: User who updated the content.

updated_at

Type: string

Required: conditional

Notes: RFC3339 timestamp for update.

deleted_by

Type: string

Required: conditional

Notes: User who deleted the content.

deleted_at

Type: string

Required: conditional

Notes: RFC3339 timestamp for delete.

published_by

Type: string

Required: conditional

Notes: User who published the content.

published_at

Type: string

Required: conditional

Notes: RFC3339 timestamp for publish.

archived_by

Type: string

Required: conditional

Notes: User who archived the content.

archived_at

Type: string

Required: conditional

Notes: RFC3339 timestamp for archive.

restored_by

Type: string

Required: conditional

Notes: User who restored the content.

restored_at

Type: string

Required: conditional

Notes: RFC3339 timestamp for restore.

verified_by

Type: string

Required: conditional

Notes: User who marked the content verified.

verified_at

Type: string

Required: conditional

Notes: RFC3339 timestamp for verify.

source

Type: string

Required: conditional

Notes: Original content source when present.

page_host

Type: string

Required: conditional

Notes: Associated page host when available.

page_path

Type: string

Required: conditional

Notes: Associated page path when available.

company_id

Type: string

Required: conditional

Notes: Company identifier, currently included on content.created.

fields_changed

Type: string[]

Required: conditional

Notes: Field list included on content.updated.

old_status

Type: string

Required: conditional

Notes: Previous status on updated, published, archived, and restored events.

new_status

Type: string

Required: conditional

Notes: New status included on content.updated.

review_interval_days

Type: number

Required: conditional

Notes: Review cadence included on content.verified.

note

Type: string

Required: conditional

Notes: Verification note included on content.verified.

owner_user_id

Type: string

Required: conditional

Notes: Assigned owner for content.verified.

content_title

Type: string

Required: conditional

Notes: Title snapshot included on content.verified.

next_review_at

Type: string

Required: conditional

Notes: Next scheduled review timestamp when available.

recording_steps[]

Type: object[]

Required: conditional

Notes: Structured recording steps included on content.created when the source provides them.

Production delivery payload examplecurl / json
{
  "event": "content.updated",
  "event_id": "evt_01JX9ZK1M9N8",
  "workspace_id": "ws_123",
  "occurred_at": "2026-02-28T14:22:11Z",
  "source_service": "content",
  "data": {
    "content_id": "cnt_123",
    "workspace_id": "ws_123",
    "updated_by": "usr_42",
    "updated_at": "2026-02-28T14:22:11Z",
    "source": "extension",
    "page_host": "app.example.com",
    "page_path": "/refunds/partial",
    "fields_changed": ["title", "body", "tags"],
    "old_status": "draft",
    "new_status": "draft"
  }
}

Notes

  • Webhook target_url must resolve to a public HTTPS endpoint.
  • Webhook subscriptions are persisted and automatic delivery is active for content events.
  • Supported automatic event types are content.created, content.updated, content.deleted, content.published, content.archived, content.restored, and content.verified.
DELETE

/workspaces/{workspaceId}/webhooks/{webhookId}

Delete a webhook subscription.

Scope: write_content

Summary

Delete a webhook subscription.

Response fields

data.success

Type: boolean

Required: yes

Notes: Mutation result for delete or revoke style operations.

Referenced type fields

WebhookHeaders fields

Content-Type

Type: header

Required: yes

Notes: Always application/json.

X-ContextPilot-Event

Type: header

Required: yes

Notes: Same normalized value as payload.event.

X-ContextPilot-Signature

Type: header

Required: yes

Notes: HMAC SHA256 signature in the form sha256=<digest>.

X-ContextPilot-Webhook-Id

Type: header

Required: yes

Notes: Webhook subscription identifier.

X-ContextPilot-Event-Id

Type: header

Required: yes

Notes: Same value as payload.event_id for production deliveries; empty for webhook.test.

WebhookEventPayload fields

event

Type: string

Required: yes

Notes: Normalized event name, such as content.created or content.verified.

event_id

Type: string

Required: yes

Notes: Unique event envelope identifier used for tracing and deduplication.

workspace_id

Type: string

Required: yes

Notes: Workspace that emitted the event.

occurred_at

Type: string

Required: yes

Notes: RFC3339 timestamp for the original domain event.

source_service

Type: string

Required: yes

Notes: Originating internal service, currently content.

data

Type: WebhookEventData

Required: yes

Notes: Event-specific payload fields. Shape depends on the event type.

WebhookEventData fields

content_id

Type: string

Required: yes

Notes: Content identifier for all currently supported automatic webhook events.

workspace_id

Type: string

Required: yes

Notes: Repeated inside event data for easier consumer-side routing.

type

Type: string

Required: conditional

Notes: Content type, included on content.created.

title

Type: string

Required: conditional

Notes: Content title, included on content.created.

created_by

Type: string

Required: conditional

Notes: User who created the content.

created_at

Type: string

Required: conditional

Notes: RFC3339 timestamp for creation.

updated_by

Type: string

Required: conditional

Notes: User who updated the content.

updated_at

Type: string

Required: conditional

Notes: RFC3339 timestamp for update.

deleted_by

Type: string

Required: conditional

Notes: User who deleted the content.

deleted_at

Type: string

Required: conditional

Notes: RFC3339 timestamp for delete.

published_by

Type: string

Required: conditional

Notes: User who published the content.

published_at

Type: string

Required: conditional

Notes: RFC3339 timestamp for publish.

archived_by

Type: string

Required: conditional

Notes: User who archived the content.

archived_at

Type: string

Required: conditional

Notes: RFC3339 timestamp for archive.

restored_by

Type: string

Required: conditional

Notes: User who restored the content.

restored_at

Type: string

Required: conditional

Notes: RFC3339 timestamp for restore.

verified_by

Type: string

Required: conditional

Notes: User who marked the content verified.

verified_at

Type: string

Required: conditional

Notes: RFC3339 timestamp for verify.

source

Type: string

Required: conditional

Notes: Original content source when present.

page_host

Type: string

Required: conditional

Notes: Associated page host when available.

page_path

Type: string

Required: conditional

Notes: Associated page path when available.

company_id

Type: string

Required: conditional

Notes: Company identifier, currently included on content.created.

fields_changed

Type: string[]

Required: conditional

Notes: Field list included on content.updated.

old_status

Type: string

Required: conditional

Notes: Previous status on updated, published, archived, and restored events.

new_status

Type: string

Required: conditional

Notes: New status included on content.updated.

review_interval_days

Type: number

Required: conditional

Notes: Review cadence included on content.verified.

note

Type: string

Required: conditional

Notes: Verification note included on content.verified.

owner_user_id

Type: string

Required: conditional

Notes: Assigned owner for content.verified.

content_title

Type: string

Required: conditional

Notes: Title snapshot included on content.verified.

next_review_at

Type: string

Required: conditional

Notes: Next scheduled review timestamp when available.

recording_steps[]

Type: object[]

Required: conditional

Notes: Structured recording steps included on content.created when the source provides them.

Production delivery payload examplecurl / json
{
  "event": "content.updated",
  "event_id": "evt_01JX9ZK1M9N8",
  "workspace_id": "ws_123",
  "occurred_at": "2026-02-28T14:22:11Z",
  "source_service": "content",
  "data": {
    "content_id": "cnt_123",
    "workspace_id": "ws_123",
    "updated_by": "usr_42",
    "updated_at": "2026-02-28T14:22:11Z",
    "source": "extension",
    "page_host": "app.example.com",
    "page_path": "/refunds/partial",
    "fields_changed": ["title", "body", "tags"],
    "old_status": "draft",
    "new_status": "draft"
  }
}

Notes

  • Webhook subscriptions are persisted and automatic delivery is active for content events.
  • Supported automatic event types are content.created, content.updated, content.deleted, content.published, content.archived, content.restored, and content.verified.
POST

/workspaces/{workspaceId}/webhooks/{webhookId}/test

Send a signed test delivery and record delivery logs.

Scope: write_content

Summary

Send a signed test delivery and record delivery logs.

Response fields

target_url

Type: string

Required: yes

Notes: Webhook target used for the test delivery.

headers

Type: object

Required: yes

Notes: Signed request headers used for the outbound test delivery.

payload

Type: string

Required: yes

Notes: Serialized JSON body sent during the test delivery.

delivered

Type: boolean

Required: yes

Notes: Whether the test request was delivered successfully.

attempts

Type: number

Required: yes

Notes: Retry attempts made during the test.

response_status

Type: number

Required: no

Notes: Final downstream HTTP status code.

last_error

Type: string

Required: no

Notes: Last transport or downstream error when delivery fails.

Referenced type fields

WebhookHeaders fields

Content-Type

Type: header

Required: yes

Notes: Always application/json.

X-ContextPilot-Event

Type: header

Required: yes

Notes: Same normalized value as payload.event.

X-ContextPilot-Signature

Type: header

Required: yes

Notes: HMAC SHA256 signature in the form sha256=<digest>.

X-ContextPilot-Webhook-Id

Type: header

Required: yes

Notes: Webhook subscription identifier.

X-ContextPilot-Event-Id

Type: header

Required: yes

Notes: Same value as payload.event_id for production deliveries; empty for webhook.test.

WebhookTestPayload fields

event

Type: string

Required: yes

Notes: Always webhook.test for the explicit test route.

workspace_id

Type: string

Required: yes

Notes: Workspace linked to the webhook subscription.

webhook_id

Type: string

Required: yes

Notes: Webhook subscription identifier under test.

sent_at

Type: string

Required: yes

Notes: RFC3339 timestamp for the test send.

Test delivery payload examplecurl / json
{
  "event": "webhook.test",
  "workspace_id": "ws_123",
  "webhook_id": "wh_123",
  "sent_at": "2026-02-28T14:30:00Z"
}

Notes

  • Webhook target_url must resolve to a public HTTPS endpoint.
  • This endpoint performs a real outbound POST and writes to delivery logs.
  • It uses the same signing model as production deliveries, but the test payload is webhook.test instead of a business event.
  • For webhook.test, X-ContextPilot-Event-Id is intentionally empty.
GET

/workspaces/{workspaceId}/webhooks/{webhookId}/deliveries

List delivery attempts for a webhook.

Scope: read_content

Summary

List delivery attempts for a webhook.

Request fields

page

Type: number

Required: no

Notes: 1-based page number. Defaults to 1.

page_size

Type: number

Required: no

Notes: Items per page. Defaults to 20 unless noted otherwise on the route.

Response fields

data[]

Type: WebhookDelivery[]

Required: yes

Notes: Delivery attempt log entries for the webhook.

data[].response_status

Type: number

Required: no

Notes: Recorded downstream status code per attempt.

meta.total

Type: number

Required: yes

Notes: Total recorded attempts matching the current query.

meta.page

Type: number

Required: yes

Notes: Current 1-based page number.

meta.page_size

Type: number

Required: yes

Notes: Page size applied to this response.

meta.total_pages

Type: number

Required: yes

Notes: Total number of pages for the current query.

Referenced type fields

WebhookDelivery fields

id

Type: string

Required: yes

Notes: Delivery log identifier.

attempt

Type: number

Required: yes

Notes: Retry attempt number.

response_status

Type: number

Required: no

Notes: Downstream HTTP status code when available.

delivered

Type: boolean

Required: yes

Notes: Whether this delivery attempt succeeded.

created_at

Type: string

Required: yes

Notes: RFC3339 timestamp.

Notes

  • Workspace path params always scope nested resources to a single workspace boundary.

Common patterns

Pagination

List endpoints accept page and page_size. Paginated routes return meta.total, meta.page, meta.page_size, and meta.total_pages.

Request tracing

Responses include request correlation metadata and respect rate-limit headers.

Key lifecycle

Create, rotate, and revoke credentials in Dashboard / Settings / API.

Need help integrating?

Start with workspace discovery, then issue a token and test your content and webhook loop against one workspace before expanding scopes.

Talk to the team