Themes

Themes control fonts, colours and branding assets used across headless experiences. You can create, update and delete themes via the API.

Get themes Build and above

Use this endpoint to list themes in your workspace. With an API key, GET /v1/headless/themes returns workspace-level themes only.

GET/v1/headless/themes

Query parameters

Field	Type	Required	Default	Description	Options
`length`	`number`	No	—		—

Examples

cURL request

curl --request GET \
  --url "https://api.coassemble.com/api/v1/headless/themes?length=50" \
  --header "Authorization: COASSEMBLE:YOUR_WORKSPACE_ID:YOUR_API_KEY"

Response

JSON response

[
  {
    "id": 1234,
    "name": "example",
    "logoId": 1234,
    "default": false,
    "logo": {
      "id": 1234,
      "path": "example",
      "name": "example"
    },
    "clientId": 1234,
    "clientIdentifier": "client_123",
    "courses": [
      {
        "id": 1234,
        "name": "example"
      }
    ],
    "created": "2026-11-07T04:29:35.031Z",
    "updated": "2026-11-07T04:29:35.031Z"
  }
]

Get theme Build and above

Use this endpoint to fetch a single theme by ID.

GET/v1/headless/themes/{id}

Path parameters

Field	Description	Options
`id`	Theme ID	—

Examples

cURL request

curl --request GET \
  --url "https://api.coassemble.com/api/v1/headless/themes/1234" \
  --header "Authorization: COASSEMBLE:YOUR_WORKSPACE_ID:YOUR_API_KEY"

Response

JSON response

{
  "id": 1234,
  "name": "example",
  "logoId": 1234,
  "default": false,
  "logo": {
    "id": 1234,
    "path": "example",
    "name": "example"
  },
  "clientId": 1234,
  "clientIdentifier": "client_123",
  "courses": [
    {
      "id": 1234,
      "name": "example"
    }
  ],
  "created": "2026-11-07T04:29:35.031Z",
  "updated": "2026-11-07T04:29:35.031Z"
}

Create theme Build and above

Use this endpoint to create a new theme.

cover-specific colour fields are ignored by this endpoint.

To set a logo, send either logoId or logoUrl, not both (a request with both returns 400, even when logoId is null). logoId is the ID of a logo that already exists in your workspace and tenant: the logoId from an earlier theme response, or a logo uploaded in the app. logoUrl is an https link to an image, or a base64 data: URL such as data:image/png;base64,.... The server downloads and stores the image, creates a logo owned by the theme's workspace and tenant, and returns its ID as logoId, so you can reuse it on other themes. Allowed types are PNG, JPEG, GIF, WebP and SVG, up to 50 MB. A link that cannot be fetched, is too large or is not an allowed image type returns 400 with the reason. Sending logoUrl needs the custom branding feature on your plan.

POST/v1/headless/themes

Body parameters

Field	Type	Required	Desc	Options
`name`	`string`	Yes	Theme name	—
`fonts`	`object`	No	Font settings ({ heading: { family }, body: { family } })	—
`colours`	`object`	No	Colour palette (keyed by role)	—
`logoId`	`number \| null`	No	Asset ID of an existing logo in the same workspace and tenant, for example the logoId from a previous theme response or a logo uploaded in the app. To add a new logo from an image, send logoUrl instead.	—
`logoUrl`	`string`	No	An https link to an image, or a base64 data: URL (data:image/png;base64,...). The server downloads and stores the image, creates a logo asset owned by the theme's workspace and tenant, and sets it as the theme's logo. Allowed types are PNG, JPEG, GIF, WebP and SVG, up to 50 MB. Send either logoId or logoUrl, not both.	—
`config`	`object`	No	Additional theme configuration	—

Examples

cURL request

curl --request POST \
  --url "https://api.coassemble.com/api/v1/headless/themes" \
  --header "Authorization: COASSEMBLE:YOUR_WORKSPACE_ID:YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "example",
    "fonts": {
        "key": "value"
    },
    "colours": {
        "key": "value"
    },
    "logoId": 1234
}'

Response

JSON response

{
  "id": 1234,
  "name": "example",
  "logoId": 1234,
  "default": false,
  "logo": {
    "id": 1234,
    "path": "example",
    "name": "example"
  },
  "clientId": 1234,
  "clientIdentifier": "client_123",
  "courses": [
    {
      "id": 1234,
      "name": "example"
    }
  ],
  "created": "2026-11-07T04:29:35.031Z",
  "updated": "2026-11-07T04:29:35.031Z"
}

Update theme Build and above

Use this endpoint to update an existing theme.

cover-specific colour fields are ignored by this endpoint.

logoId and logoUrl work as in Create theme. Sending logoUrl replaces the theme's logo with a newly stored image; the previous logo stays in the library.

PUT/v1/headless/themes/{id}

Path parameters

Field	Description	Options
`id`	Theme ID	—

Body parameters

Field	Type	Required	Desc	Options
`name`	`string`	Yes	Theme name	—
`fonts`	`object`	No	Font settings	—
`colours`	`object`	No	Colour palette	—
`logoId`	`number \| null`	No	Asset ID of an existing logo in the same workspace and tenant, for example the logoId from a previous theme response or a logo uploaded in the app. To add a new logo from an image, send logoUrl instead.	—
`logoUrl`	`string`	No	An https link to an image, or a base64 data: URL (data:image/png;base64,...). The server downloads and stores the image, creates a logo asset owned by the theme's workspace and tenant, and sets it as the theme's logo. Allowed types are PNG, JPEG, GIF, WebP and SVG, up to 50 MB. Send either logoId or logoUrl, not both.	—
`config`	`object`	No	Additional theme configuration	—
`default`	`boolean`	No	Whether this theme is the workspace default	—

Examples

cURL request

curl --request PUT \
  --url "https://api.coassemble.com/api/v1/headless/themes/1234" \
  --header "Authorization: COASSEMBLE:YOUR_WORKSPACE_ID:YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "example",
    "fonts": {
        "key": "value"
    },
    "colours": {
        "key": "value"
    },
    "logoId": 1234
}'

Response

JSON response

{
  "id": 1234,
  "name": "example",
  "logoId": 1234,
  "default": false,
  "logo": {
    "id": 1234,
    "path": "example",
    "name": "example"
  },
  "clientId": 1234,
  "clientIdentifier": "client_123",
  "courses": [
    {
      "id": 1234,
      "name": "example"
    }
  ],
  "created": "2026-11-07T04:29:35.031Z",
  "updated": "2026-11-07T04:29:35.031Z"
}

Delete theme Build and above

Use this endpoint to delete an existing theme.

DELETE/v1/headless/themes/{id}

Path parameters

Field	Description	Options
`id`	Theme ID	—

Examples

cURL request

curl --request DELETE \
  --url "https://api.coassemble.com/api/v1/headless/themes/1234" \
  --header "Authorization: COASSEMBLE:YOUR_WORKSPACE_ID:YOUR_API_KEY"

Response

JSON response

{
  "success": false
}