Feature something on the rail
POST /admin/featured
Adds an asset, collection or team to the featured rail. You need
system.admin.
The subject isn’t checked: any id is accepted, whether or not it
exists or anyone can see it. Featuring doesn’t change who can see
the subject. Readers only see placements for things they can already
see, and a team placement appears on the teams rail rather than
the featured rail.
Leave position out to add after the last placement on the rail, or
give a number to use it as is. Other placements don’t move, so
positions can repeat; two adds at the same moment can also get the
same position.
scope sets the audience: org for signed-in users, the default,
or public to include visitors who aren’t signed in. The same
subject can be on the rail once per audience; adding it again for
the same audience gets 409.
The response is the placement as stored, so title and subtitle
are empty and the preview flags are false. List the rail again to
see it resolved.
Authorizations
Section titled “Authorizations ”Request Body required
Section titled “Request Body required ”What to feature on the rail.
object
What subject_id points at. A team placement is shown on the
teams rail (GET /featured/teams), not on the featured rail.
Where to put it. Leave it out or send null to add after the last
placement on the rail. A number is used as is: other placements
don’t move, so two can share a position.
Who sees the placement: org for signed-in users, or public to
include visitors who aren’t signed in, when the instance lets them
browse. Left out, it’s org. Any other value, including team,
gets a 400.
Responses
Section titled “ Responses ”The new placement, as stored.
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
The placement’s id, used to reorder or remove it. It isn’t the subject’s id.
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.
Its place in the order: lower numbers come first, and equal numbers go oldest first. Positions can repeat and have gaps.
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.
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.
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.
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.
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.
The vertical half of the crop centre, as a fraction of the picture’s
height. See cover_focal_x.
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.
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.
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.
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.
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
The handle. Also the profile link target
(/users/by-username/{username}).
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.
The avatar URL stored on the user’s profile, if there is one; left out when none is stored.
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.
Malformed request
object
Human-readable error summary
Example
the request could not be completedAuthentication required, missing, or invalid
object
Human-readable error summary
Example
the request could not be completedExample
{ "error": "authentication required: sign in and retry with a valid session or API token"}Authenticated but missing required capabilities
object
Human-readable error summary
Example
the request could not be completedThat subject is already on the rail for this audience.
object
Human-readable error summary
Example
the request could not be completed