Curate or update content

POST

/api/v3/curations

curl --request POST \
  --url https://api.tryletterhead.com/api/v3/curations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form api=true \
  --form url=https://letterhead.ai \
  --form 'channels[]=letterhead-example-newsletter' \
  --form content=example \
  --form excerpt=example \
  --form image=example \
  --form siteName=example \
  --form publicationDate=example \
  --form tags=example \
  --form title=example

• Production

Create a curation for any channel within the company. Note that the v3 api requires a key generated from within the company-level settings, which are available only to folks with that given plan.

This endpoint always creates (or updates) a single, company-level curation — channels does not create a separate copy per channel here, it only controls which channels can see and use it. Resubmitting the same url (matched together with its type and, if it came from a feed, the feed it came from) updates that existing curation rather than creating a new one. If that resubmission includes channels, the list you pass replaces which channels the curation is shared with; if it leaves channels out, the existing sharing is kept as it was. The bulk endpoint below behaves differently: there, channels creates one separate curation per channel.

channels accepts any number of channel identifiers. When you first curate a url, you can also omit it entirely, which shares the new curation with every channel in the company instead of restricting it to specific ones. Omitting it on a later resubmission does not widen an existing curation back to every channel.

This endpoint persists exactly the fields you supply — it does not crawl url for Open Graph data on your behalf. If you omit title, excerpt, image, or the other content fields, the curation is saved without them; fetch and pass those values yourself if you want them populated.

Authorizations

• bearerAuth

Request Body ^required

Media type multipart/form-data

object

api

required

Set to true to authenticate with your company API key rather than a signed-in session.

string

Example

true

url

required

URL of the content being curated. Saved as provided — this endpoint does not fetch or crawl the URL for Open Graph data.

string

Example

https://letterhead.ai

channels[]

string[] | An array of channel identifiers (or channel “slugs”) across which to create a curation. Optional — on a new curation, omit it to share the curation with every channel in the company; on a resubmission, omitting it keeps the existing sharing, and passing it replaces that sharing.

Array<string>

Example

[
  "letterhead-example-newsletter"
]

content

html content for the curation, only p and formatting elements are allowed.

string

excerpt

Plain text excerpt of the curated content. Saved as provided — this endpoint does not fetch or crawl the URL for one.

string

image

The URL of a featured image to associate with this piece of content.

string

siteName

The name of the site the curated content originated from.

string

publicationDate

The Y-md H:i:s formatted date of publication.

string

tags

string[] | An optional array of string tags with which to associate this piece of content. Example: ['dogs', 'canines']

string

title

Title of the curated content. Saved as provided — this endpoint does not fetch or crawl the URL for one.

string

Responses

201

Curation created (or updated, if a curation for the same url already existed). The saved curation is returned in items; use its uniqueId with the other curation endpoints.

Media type application/json

object

items

The saved curation.

object

uniqueId

string

title

string

excerpt

string

content

string

author

string

siteName

string

originalUrl

string

image

string

imageAlt

string

imageCaption

string

source

string

type

integer

curated

boolean

feedUniqueId

string

publicationDate

string

createdAt

string

updatedAt

string

tags

Array<string>

message

string

total

integer

Example

{
  "message": "Curation created.",
  "total": 1
}