CMS · home surfaces
16 routes. Paths are relative to https://api.intersink.com/v1.
- GET/cms/channels/{channelId}/surfacesThe channel's home surfaces (summaries)
- POST/cms/channels/{channelId}/surfacesCreate a surface (a draft; publish it when ready)
- GET/cms/channels/{channelId}/surfaces/{surface}One surface: its draft blocks, status and published summary (ETag = version)
- PUT/cms/channels/{channelId}/surfaces/{surface}Replace the draft: title, description and/or the whole ordered block list
- DELETE/cms/channels/{channelId}/surfaces/{surface}Delete a surface (it disappears from clients at once)
- POST/cms/channels/{channelId}/surfaces/{surface}/blocksAdd one block (at `position`, default the end)
- PATCH/cms/channels/{channelId}/surfaces/{surface}/blocks/{blockId}Change one block (null clears a field)
- DELETE/cms/channels/{channelId}/surfaces/{surface}/blocks/{blockId}Remove one block
- PUT/cms/channels/{channelId}/surfaces/{surface}/blocks/orderReorder: every block id, in the new order
- POST/cms/channels/{channelId}/surfaces/{surface}/discardDrop unpublished changes: the draft goes back to what is published
- GET/cms/channels/{channelId}/surfaces/{surface}/historyWho changed and published the surface, newest first (max 100): by is the person's name (or address when they have none), by_email their address
- GET/cms/channels/{channelId}/surfaces/{surface}/previewWhat one audience sees: the draft (default) or the published surface, filtered like the public read
- POST/cms/channels/{channelId}/surfaces/{surface}/publishPublish the draft as it is at `version`; clients refresh within seconds
- POST/cms/channels/{channelId}/surfaces/{surface}/unpublishTake the surface off clients (the draft stays)
- POST/cms/channels/{channelId}/surfaces/check-blockValidate one block without saving it (returns its stored form or 400 with every problem)
- POST/cms/channels/{channelId}/surfaces/imagesUpload an image for the channel's surfaces (field: image; PNG, JPEG, WebP or GIF, up to 2 MB) → {id, url}; use id as a block's image
The channel's home surfaces (summaries)
GET/cms/channels/{channelId}/surfaces
Needs a signed-in user (Bearer token or access_token cookie).
Parameters
| Name | Type | Description |
|---|---|---|
| channelIdrequired | string, path |
Response
200. The payload in data is not described in the spec yet.
Create a surface (a draft; publish it when ready)
POST/cms/channels/{channelId}/surfaces
Needs a signed-in user (Bearer token or access_token cookie).
Parameters
| Name | Type | Description |
|---|---|---|
| channelIdrequired | string, path |
Request body application/json
| Field | Type | Description |
|---|---|---|
| namerequired | string | 1–48 lower-case letters, digits or dashes Example: "start" |
| title | string | At most 80 characters. Example: "Start page" |
| description | string | At most 300 characters. |
| blocks | object[] | Ordered blocks. Each is {type: banner|shortcut|ad|text, id? (keep to update, omit for new), enabled?, key?, starts_at?, ends_at?, locales?, countries? | exclude_countries?, platforms?} plus its type's fields (see docs/home-surfaces.md). |
Response
201. The payload in data is of type object.
One surface: its draft blocks, status and published summary (ETag = version)
GET/cms/channels/{channelId}/surfaces/{surface}
Needs a signed-in user (Bearer token or access_token cookie).
Parameters
| Name | Type | Description |
|---|---|---|
| channelIdrequired | string, path | |
| surfacerequired | string, path |
Response
200. The payload in data is of type object.
Replace the draft: title, description and/or the whole ordered block list
PUT/cms/channels/{channelId}/surfaces/{surface}
Needs a signed-in user (Bearer token or access_token cookie).
Parameters
| Name | Type | Description |
|---|---|---|
| channelIdrequired | string, path | |
| surfacerequired | string, path | |
| if-match | string, header | |
| If-Match | string, header |
Request body application/json
| Field | Type | Description |
|---|---|---|
| version | number | The version you are replacing (or send If-Match: "<version>") |
| title | string | At most 80 characters. |
| description | string | At most 300 characters. |
| blocks | object[] | Ordered blocks. Each is {type: banner|shortcut|ad|text, id? (keep to update, omit for new), enabled?, key?, starts_at?, ends_at?, locales?, countries? | exclude_countries?, platforms?} plus its type's fields (see docs/home-surfaces.md). |
Response
200. The payload in data is of type object.
Delete a surface (it disappears from clients at once)
DELETE/cms/channels/{channelId}/surfaces/{surface}
Needs a signed-in user (Bearer token or access_token cookie).
Parameters
| Name | Type | Description |
|---|---|---|
| channelIdrequired | string, path | |
| surfacerequired | string, path | |
| if-match | string, header | |
| version | string, query | |
| If-Match | string, header |
Response
200. The payload in data is not described in the spec yet.
Add one block (at `position`, default the end)
POST/cms/channels/{channelId}/surfaces/{surface}/blocks
Needs a signed-in user (Bearer token or access_token cookie).
Parameters
| Name | Type | Description |
|---|---|---|
| channelIdrequired | string, path | |
| surfacerequired | string, path | |
| if-match | string, header |
Request body application/json
| Field | Type | Description |
|---|---|---|
| version | number | The version you saw (or send If-Match: "<version>") |
| blockrequired | object | Ordered blocks. Each is {type: banner|shortcut|ad|text, id? (keep to update, omit for new), enabled?, key?, starts_at?, ends_at?, locales?, countries? | exclude_countries?, platforms?} plus its type's fields (see docs/home-surfaces.md). |
| position | number | Index to insert at (default: the end) |
Response
201. The payload in data is of type object.
Change one block (null clears a field)
PATCH/cms/channels/{channelId}/surfaces/{surface}/blocks/{blockId}
Needs a signed-in user (Bearer token or access_token cookie).
Parameters
| Name | Type | Description |
|---|---|---|
| channelIdrequired | string, path | |
| surfacerequired | string, path | |
| blockIdrequired | string, path | |
| if-match | string, header |
Request body application/json
| Field | Type | Description |
|---|---|---|
| version | number | The version you saw (or send If-Match: "<version>") |
| blockrequired | object | Fields to change; null clears a field. The type can't change. |
Response
200. The payload in data is of type object.
Remove one block
DELETE/cms/channels/{channelId}/surfaces/{surface}/blocks/{blockId}
Needs a signed-in user (Bearer token or access_token cookie).
Parameters
| Name | Type | Description |
|---|---|---|
| channelIdrequired | string, path | |
| surfacerequired | string, path | |
| blockIdrequired | string, path | |
| if-match | string, header | |
| version | string, query |
Response
200. The payload in data is of type object.
Reorder: every block id, in the new order
PUT/cms/channels/{channelId}/surfaces/{surface}/blocks/order
Needs a signed-in user (Bearer token or access_token cookie).
Parameters
| Name | Type | Description |
|---|---|---|
| channelIdrequired | string, path | |
| surfacerequired | string, path | |
| if-match | string, header |
Request body application/json
| Field | Type | Description |
|---|---|---|
| version | number | The version you saw (or send If-Match: "<version>") |
| idsrequired | string[] | Every block id, in the new order |
Response
200. The payload in data is of type object.
Drop unpublished changes: the draft goes back to what is published
POST/cms/channels/{channelId}/surfaces/{surface}/discard
Needs a signed-in user (Bearer token or access_token cookie).
Parameters
| Name | Type | Description |
|---|---|---|
| channelIdrequired | string, path | |
| surfacerequired | string, path | |
| if-match | string, header |
Request body application/json
| Field | Type | Description |
|---|---|---|
| version | number | The version you saw (or send If-Match: "<version>") |
Response
200. The payload in data is of type object.
Who changed and published the surface, newest first (max 100): by is the person's name (or address when they have none), by_email their address
GET/cms/channels/{channelId}/surfaces/{surface}/history
Needs a signed-in user (Bearer token or access_token cookie).
Parameters
| Name | Type | Description |
|---|---|---|
| channelIdrequired | string, path | |
| surfacerequired | string, path | |
| limitrequired | string, query |
Response
200. The payload in data is not described in the spec yet.
What one audience sees: the draft (default) or the published surface, filtered like the public read
GET/cms/channels/{channelId}/surfaces/{surface}/preview
Needs a signed-in user (Bearer token or access_token cookie).
Parameters
| Name | Type | Description |
|---|---|---|
| channelIdrequired | string, path | |
| surfacerequired | string, path | |
| of | string, query | One of: "draft", "published". |
| at | any, query | ISO time to preview a schedule |
| country | any, query | Example: "GB" |
| platform | any, query | Example: "windows" |
| locale | any, query | Example: "en-GB" |
Response
200. The payload in data is of type object.
Publish the draft as it is at `version`; clients refresh within seconds
POST/cms/channels/{channelId}/surfaces/{surface}/publish
Needs a signed-in user (Bearer token or access_token cookie).
Parameters
| Name | Type | Description |
|---|---|---|
| channelIdrequired | string, path | |
| surfacerequired | string, path | |
| if-match | string, header |
Request body application/json
| Field | Type | Description |
|---|---|---|
| version | number | The version you saw (or send If-Match: "<version>") |
Response
200. The payload in data is of type object.
Take the surface off clients (the draft stays)
POST/cms/channels/{channelId}/surfaces/{surface}/unpublish
Needs a signed-in user (Bearer token or access_token cookie).
Parameters
| Name | Type | Description |
|---|---|---|
| channelIdrequired | string, path | |
| surfacerequired | string, path | |
| if-match | string, header |
Request body application/json
| Field | Type | Description |
|---|---|---|
| version | number | The version you saw (or send If-Match: "<version>") |
Response
200. The payload in data is of type object.
Validate one block without saving it (returns its stored form or 400 with every problem)
POST/cms/channels/{channelId}/surfaces/check-block
Needs a signed-in user (Bearer token or access_token cookie).
Parameters
| Name | Type | Description |
|---|---|---|
| channelIdrequired | string, path |
Request body application/json
| Field | Type | Description |
|---|---|---|
| blockrequired | object |
Response
201. The payload in data is not described in the spec yet.
Upload an image for the channel's surfaces (field: image; PNG, JPEG, WebP or GIF, up to 2 MB) → {id, url}; use id as a block's image
POST/cms/channels/{channelId}/surfaces/images
Needs a signed-in user (Bearer token or access_token cookie).
Parameters
| Name | Type | Description |
|---|---|---|
| channelIdrequired | string, path |
Response
201. The payload in data is not described in the spec yet.