Skip to content

Create or replace the promo band

PUT
/admin/featured/promo

Saves the promo band, creating it if there isn’t one yet. You need system.admin.

Every save replaces the whole definition. A field you leave out or send as null isn’t kept: it goes back to its default, so blurb and the button become empty, enabled false, after_page 1 and scope org. Text is trimmed. The band’s cards aren’t changed.

An empty headline is allowed, but readers don’t see the band until it has one. Send cta_label and cta_url together, or neither. cta_url must be a lower-case http:// or https:// URL with a host, or a path on this site such as /collections. Other values are refused, including javascript: links and //host addresses: most get a 400, but a bare / or a scheme with capital letters currently fails with a 500. An after_page below 1 gets a 400.

The response is the band read back after saving, with its cards. That read is a separate step: if it fails you get an error, but the band was still saved.

The whole band definition. Each save replaces every field; a field you leave out goes back to its default.

object
title
required

The headline, trimmed. A missing title isn’t refused: it’s saved as empty, and readers don’t see a band without a headline.

string
blurb

Optional text under the headline, trimmed. Left out or null, it’s saved empty.

string
""
cta_label

The button’s text, trimmed. Send it with cta_url, or leave both empty for no button; one without the other gets a 400.

string
""
cta_url

Where the button goes. The description of this operation says what’s accepted.

string
""
enabled

Whether readers see the band. Left out or null, it’s saved switched off.

boolean
after_page

Which page of the browse feed the band follows. Left out, it’s 1; below 1 gets a 400.

integer
default: 1 >= 1
scope

Who the band is for: org for signed-in users, or public to include visitors who aren’t signed in. Left out, it’s org.

string
default: org
Allowed values: public org

The saved band, read back with its cards.

The promo band: a headline, an optional line of text, an optional button and a row of cards, shown between pages of the browse feed. GET /featured/promo returns it only when it’s switched on, meant for the reader, has a headline and has at least one card the reader can see; otherwise that response has no band. The admin endpoints return it as stored, with every card.

object
id
required
string format: uuid
title
required

The headline. Readers never see a band whose headline is empty.

string
blurb
required

The short line under the headline. May be empty.

string
cta_label
required

The button’s text, or empty for no button. It’s always set together with cta_url.

string
cta_url
required

Where the button goes: an http or https URL, or a path on this site. Empty when there’s no button. It becomes a link on the browse page for everyone who sees the band, which is why PUT /admin/featured/promo restricts it.

string
enabled
required

Whether the band is switched on. Readers never see a band that’s off; the admin endpoints still return it.

boolean
after_page
required

Which page of the browse feed the band follows: 1 places it after the first page. Artist Alley’s browse page loads 36 posts a page and shows the band once more than 36 times after_page posts have loaded, so a shorter feed doesn’t show it. The list view never shows it.

integer
>= 1
scope
required

Who the band is for: org for signed-in users, or public to include visitors who aren’t signed in, when the instance lets them browse. Cards take their audience from the band.

string
Allowed values: public org
items
required

The cards, in order. GET /featured/promo returns only the cards the reader can see, at most 24, and never an empty list. The admin endpoints return every card unfiltered, and the list can be empty.

Array<object>

A placement: an asset, collection or team featured on the rail, or a card in the promo band. Which fields are filled in depends on where it comes from. The admin lists fill in titles and cover details without checking what you may see; a newly created placement has only its stored fields; the public rail and band fill in everything for the reader and drop placements the reader can’t see.

object
id
required

The placement’s id, used to reorder or remove it. It isn’t the subject’s id.

string format: uuid
subject_kind
required

What subject_id points at. Only the admin rail list and a newly created rail placement return team; the public rail and the band never do.

string
Allowed values: asset collection team
subject_id
required
string format: uuid
position
required

Its place in the order: lower numbers come first, and equal numbers go oldest first. Positions can repeat and have gaps.

integer
title
required

The subject’s title or name. In the admin lists it’s empty when the subject no longer exists; a subject that was deleted but can still be restored keeps its title. A newly created placement returns it empty.

string
subtitle
required

On the public rail and band, a collection’s own description, or empty if it has none. Always empty for other subjects, in the admin lists and on a newly created placement.

string
item_count

On the public rail and band, how many of a collection’s pinned posts the reader can see, not counting pins that have expired. Left out for other subjects, in the admin lists and on a newly created placement.

integer
nullable
cover_asset_id

The asset whose picture the tile uses: the asset itself, or a picture chosen for a collection. The public rail and band use the collection’s featured cover, then its own cover, then the newest post cover the reader is allowed to see, and leave this out when there’s none. The admin lists use only the newest post cover that has a preview and don’t check what you can see, so loading the picture may still be refused. Left out for teams and on a newly created placement.

string format: uuid
nullable
cover_focal_x

On the public rail and band, where to centre the tile’s crop across the picture, as a fraction of its width (0 to 1). Set only when a collection shows its featured cover or its own cover and a centre was chosen; left out otherwise, which means centre, and always left out in the admin lists and on a newly created placement.

number format: double
nullable
cover_focal_y

The vertical half of the crop centre, as a fraction of the picture’s height. See cover_focal_x.

number format: double
nullable
cover_zoom

On the public rail and band, how much to tighten the tile’s crop, from 1 (no zoom) to 4. Set only when a collection shows its featured cover or its own cover and a zoom was chosen; left out otherwise, which means no zoom, and always left out in the admin lists and on a newly created placement.

number format: double
nullable
asset_file_hash

The content hash of the tile’s picture. The public rail and band set it only when the reader may see that picture. The admin lists set it for every asset subject that still exists and, for a collection, from the cover of its newest post that qualifies: the post and its cover aren’t deleted and the cover has a preview. They don’t check what you can see. Left out for teams and on a newly created placement.

string
nullable
preview_available
required

Whether a small preview of the tile’s picture exists. On the public rail and band it’s also false when the reader may not see the picture. The admin lists check only that the preview exists, not whether you may load it. Always false for teams and on a newly created placement.

boolean
ladder_available
required

Whether every preview size the instance is set up to make exists for the tile’s picture, with the same reader check as preview_available on the public rail and band. False when no sizes are set up, for teams and on a newly created placement.

boolean
author

Only on GET /featured/promo: the owner of the card’s asset or collection. Left out when there’s no owner to show, and for readers who aren’t signed in when the owner has asked to be hidden from them. Never set in the admin lists, on the rail or on a newly created placement.

object
ref
required
integer format: int64
username
required

The handle. Also the profile link target (/users/by-username/{username}).

string
display_name
required

The name to show, never empty: the profile’s display name, then the account’s full name, then the username, and as a last resort user followed by the account number. For readers who aren’t signed in, the account’s full name is skipped; the display name and username are still used.

string
avatar_url

The avatar URL stored on the user’s profile, if there is one; left out when none is stored.

string
nullable
created_at
required

When the placement was created. The public rail and band don’t fill it in, so there it’s always 0001-01-01T00:00:00Z.

string format: date-time
created_at
string format: date-time
updated_at
string format: date-time

Malformed request

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed