MavertoMaverto
Внешний REST API

Стройте поверх Maverto без обратной разработки продукта.

Эта страница описывает публичный API для разработчиков по адресу /api/external/v1: порядок аутентификации, границы ролей, форму данных и рабочие примеры запросов.

API-ключи для каждой компанииКороткоживущие bearer-токеныМаршруты с проверкой ролейЖурналы доставки вебхуков

Порядок аутентификации

  1. Создайте или обновите API-ключ в личном кабинете, затем откройте «Настройки» и «API».
  2. Обменяйте ключ на POST /auth/token.
  3. Полученный bearer-токен используйте для всех обращений к ресурсам.
  4. Отзывайте токены при смене учётных данных или завершении сессии.

Базовый адрес и заголовки

Все публичные маршруты размещены под /api/external/v1. API-ключ из личного кабинета нужен только для обмена на токен. Все операции с ресурсами должны использовать Authorization: Bearer <token>.

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

Ответы приходят в виде JSON-обёрток. Маршруты со списками возвращают data[] и готовое к постраничному выводу meta. Маршруты изменения возвращают один объект data.

Замечания по безопасности

API-ключи действуют в пределах компании и должны храниться в менеджере секретов.

Адреса вебхуков должны быть публичными HTTPS-endpoint'ами.

Ограничения частоты применяются к каждой интеграции отдельно.

Права проверяются на каждом маршруте. Шлюз остаётся тонким и не обходит доменные права.

Справочник endpoint'ов

Разверните любой маршрут и увидите, что уходит и что возвращается

Каждый endpoint ниже разворачивается на месте. Поля запроса, поля ответа и практические заметки остаются рядом с самим маршрутом, а не в отдельном разделе со схемами.

Справочник endpoint'ов ниже — маршруты, имена полей, типы и примеры запросов — публикуется только на английском, чтобы точно совпадать с API.

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