Introduction

Playbooks API

Overview

Organisation-scoped information library: versioned books, attachments, publish, and read acknowledgements. Catalog scope uses opaque Directory location-group and location ids. This service does not own people, places, or access roles.

Integration guide: Playbooks service docs

OpenAPI v0.1.0 · source openapi/playbooks.json

OpenAPI 3.0.0 · v0.1.0 · 20 operations

Operations

System

Liveness and generated documentation.

get/health

Health check

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/playbooks/health"

Unauthenticated liveness probe. Does not verify D1 connectivity, R2, or JWT configuration.

Operation ID: getHealth

Responses

200
Service is running
application/json

get/v1/health

Health check (versioned)

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/playbooks/v1/health"

Unauthenticated liveness probe. Alias of GET /health.

Operation ID: getHealthV1

Responses

200
Service is running
application/json

Audit

Audit log of mutations in the JWT organisation.

get/v1/audit

Playbooks audit trail

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/playbooks/v1/audit"

Operation ID: listPlaybooksAudit

Responses

200
Audit events, newest first
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: missing draft, unpublished version, or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

Catalog

Organisation catalog type definitions. Playbook items reference a catalog via `catalogId` on create.

get/v1/catalog-types

List catalog types

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/playbooks/v1/catalog-types"

Organisation-defined catalog types. Playbook items set `catalogId` to the catalog type `id` from create or list.

Operation ID: listCatalogTypes

Parameters

Name	In	Type	Description
page	query	integer	—
page_size	query	integer	—

Responses

200
Catalog types
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: missing draft, unpublished version, or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/catalog-types

Create catalog type

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/playbooks/v1/catalog-types"

Defines a catalog type (server-assigned UUID id). Label must be unique per org (case-insensitive).

Operation ID: createCatalogType

Request body(required)

application/jsonPlaybookCatalogTypeCreate

Responses

201
Catalog type created
application/json
400
Malformed JSON or otherwise unusable request. `error.code` is typically VALIDATION_ERROR.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found in this organisation. `error.code`: NOT_FOUND.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT. Typical causes: duplicate identity or immutable published version.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: missing draft, unpublished version, or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/catalog-types/{id}

Get catalog type

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/playbooks/v1/catalog-types/example-id"

Operation ID: getCatalogType

Parameters

Name	In	Type	Description
id*	path	string (uuid)	—

Responses

200
Catalog type
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found in this organisation. `error.code`: NOT_FOUND.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: missing draft, unpublished version, or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

patch/v1/catalog-types/{id}

Update catalog type

Example request

curl -sS \
  -X PATCH \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/playbooks/v1/catalog-types/example-id"

Updates label or description.

Operation ID: updateCatalogType

Parameters

Name	In	Type	Description
id*	path	string (uuid)	—

Request body(required)

application/jsonPlaybookCatalogTypePatch

Responses

200
Catalog type updated
application/json
400
Malformed JSON or otherwise unusable request. `error.code` is typically VALIDATION_ERROR.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found in this organisation. `error.code`: NOT_FOUND.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT. Typical causes: duplicate identity or immutable published version.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: missing draft, unpublished version, or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

delete/v1/catalog-types/{id}

Delete catalog type

Example request

curl -sS \
  -X DELETE \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/playbooks/v1/catalog-types/example-id"

Deletes a catalog type when no playbook items reference it.

Operation ID: deleteCatalogType

Parameters

Name	In	Type	Description
id*	path	string (uuid)	—

Responses

200
Deleted
application/json
400
Malformed JSON or otherwise unusable request. `error.code` is typically VALIDATION_ERROR.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found in this organisation. `error.code`: NOT_FOUND.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT. Typical causes: duplicate identity or immutable published version.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: missing draft, unpublished version, or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

Playbooks

Information books, draft and published versions, publish workflow, and read access. Scope via `locationGroupId` (or legacy `brandId`) and optional `locationId`.

get/v1/playbook-items

List information books

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/playbooks/v1/playbook-items"

Paginated list of information books. Optional `locationGroupId` (legacy `brandId`) and `locationId` filter which items apply in a Directory scope.

Operation ID: listPlaybookItems

Parameters

Name	In	Type	Description
page	query	integer	—
page_size	query	integer	—
locationGroupId	query	string (uuid)	Opaque Directory location-group id (`/directory/v1/location-groups`). `brandId` on legacy routes is the same value.
brandId	query	string (uuid)	Opaque Directory location-group id (`/directory/v1/location-groups`). `brandId` on legacy routes is the same value. Legacy alias of locationGroupId.
locationId	query	string (uuid)	Opaque Directory location id (`/directory/v1/locations`).

Responses

200
Playbook items
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: missing draft, unpublished version, or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/playbook-items

Create an information book

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/playbooks/v1/playbook-items"

Omit `locationGroupId` for organisation-wide books. Set group and optional `locationId` for group- or place-scoped books.

Operation ID: createPlaybookItem

Request body(required)

application/jsonPlaybookItemCreate

Responses

201
Created playbook item
application/json
400
Malformed JSON or otherwise unusable request. `error.code` is typically VALIDATION_ERROR.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found in this organisation. `error.code`: NOT_FOUND.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT. Typical causes: duplicate identity or immutable published version.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: missing draft, unpublished version, or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/playbook-items/{id}

Get an information book

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/playbooks/v1/playbook-items/example-id"

Returns metadata and content (published when available, otherwise the current draft).

Operation ID: getPlaybookItem

Parameters

Name	In	Type	Description
id*	path	string (uuid)	—

Responses

200
Playbook
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found in this organisation. `error.code`: NOT_FOUND.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: missing draft, unpublished version, or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

patch/v1/playbook-items/{id}

Update draft content

Example request

curl -sS \
  -X PATCH \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/playbooks/v1/playbook-items/example-id"

Updates the current draft body for the playbook `id`. Item metadata is set at create time only.

Operation ID: updatePlaybookItemContent

Parameters

Name	In	Type	Description
id*	path	string (uuid)	—

Request body(required)

application/jsonPlaybookItemContentUpdate

Responses

200
Updated draft content
application/json
400
Malformed JSON or otherwise unusable request. `error.code` is typically VALIDATION_ERROR.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found in this organisation. `error.code`: NOT_FOUND.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT. Typical causes: duplicate identity or immutable published version.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: missing draft, unpublished version, or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

delete/v1/playbook-items/{id}

Delete an information book

Example request

curl -sS \
  -X DELETE \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/playbooks/v1/playbook-items/example-id"

Operation ID: deletePlaybookItem

Parameters

Name	In	Type	Description
id*	path	string (uuid)	—

Responses

200
Deleted
application/json
400
Malformed JSON or otherwise unusable request. `error.code` is typically VALIDATION_ERROR.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found in this organisation. `error.code`: NOT_FOUND.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT. Typical causes: duplicate identity or immutable published version.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: missing draft, unpublished version, or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/playbook-items/{id}/publish

Publish the current draft

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/playbooks/v1/playbook-items/example-id/publish"

Operation ID: publishPlaybookItem

Parameters

Name	In	Type	Description
id*	path	string (uuid)	—

Responses

200
Published playbook item
application/json
400
Malformed JSON or otherwise unusable request. `error.code` is typically VALIDATION_ERROR.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found in this organisation. `error.code`: NOT_FOUND.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT. Typical causes: duplicate identity or immutable published version.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: missing draft, unpublished version, or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

Media

Attachments stored in R2.

post/v1/playbook-items/{id}/attachments

Upload an attachment to the draft

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/playbooks/v1/playbook-items/example-id/attachments"

Operation ID: uploadPlaybookAttachment

Parameters

Name	In	Type	Description
id*	path	string (uuid)	—

Request body(required)

multipart/form-dataobject

Responses

201
Uploaded attachment
application/json
400
Malformed JSON or otherwise unusable request. `error.code` is typically VALIDATION_ERROR.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found in this organisation. `error.code`: NOT_FOUND.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT. Typical causes: duplicate identity or immutable published version.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: missing draft, unpublished version, or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/playbook-items/{id}/attachments/{attachmentId}

Download an attachment

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/playbooks/v1/playbook-items/example-id/attachments/example-id"

Operation ID: downloadPlaybookAttachment

Parameters

Name	In	Type	Description
id*	path	string (uuid)	—
attachmentId*	path	string (uuid)	—

Responses

200
Attachment bytes
application/octet-stream
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found in this organisation. `error.code`: NOT_FOUND.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: missing draft, unpublished version, or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

User

View, assign, unassign, and acknowledge playbooks per Directory user id.

get/v1/users/{userId}/playbooks

List published playbooks for a user

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/playbooks/v1/users/example-id/playbooks"

Members may only request their own `userId`. Managers may list any user in the organisation.

Operation ID: listUserPlaybooks

Parameters

Name	In	Type	Description
userId*	path	string (uuid)	Directory user id.

Responses

200
Published playbooks
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: missing draft, unpublished version, or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/users/{userId}/playbook-assignments

Assign a playbook to a user

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/playbooks/v1/users/example-id/playbook-assignments"

Sets the item `audience` to `assigned` and creates an explicit assignment row.

Operation ID: assignUserPlaybook

Parameters

Name	In	Type	Description
userId*	path	string (uuid)	Directory user id.

Request body(required)

application/jsonUserPlaybookAssignmentCreate

Responses

200
Assignment recorded
application/json
400
Malformed JSON or otherwise unusable request. `error.code` is typically VALIDATION_ERROR.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found in this organisation. `error.code`: NOT_FOUND.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT. Typical causes: duplicate identity or immutable published version.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: missing draft, unpublished version, or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

delete/v1/users/{userId}/playbook-assignments/{id}

Remove a playbook assignment from a user

Example request

curl -sS \
  -X DELETE \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/playbooks/v1/users/example-id/playbook-assignments/example-id"

Operation ID: unassignUserPlaybook

Parameters

Name	In	Type	Description
userId*	path	string (uuid)	—
id*	path	string (uuid)	Playbook item id.

Responses

200
Assignment removed
application/json
400
Malformed JSON or otherwise unusable request. `error.code` is typically VALIDATION_ERROR.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found in this organisation. `error.code`: NOT_FOUND.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT. Typical causes: duplicate identity or immutable published version.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: missing draft, unpublished version, or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/users/{userId}/playbooks/{itemId}/acknowledge

Acknowledge a published playbook

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/playbooks/v1/users/example-id/playbooks/example-id/acknowledge"

Records a read receipt for the signed-in user (`userId` must match the JWT `actorId`).

Operation ID: acknowledgeUserPlaybook

Parameters

Name	In	Type	Description
userId*	path	string (uuid)	—
itemId*	path	string (uuid)	—

Request body(required)

application/jsonPlaybookAcknowledge

Responses

200
Acknowledgement recorded
application/json
400
Malformed JSON or otherwise unusable request. `error.code` is typically VALIDATION_ERROR.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found in this organisation. `error.code`: NOT_FOUND.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT. Typical causes: duplicate identity or immutable published version.
application/json
422
Validation or business-rule failure. `error.code`: VALIDATION_ERROR. Typical causes: missing draft, unpublished version, or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json