Sources
Watch a feed or a page and post what is new on it.
Paste a link and yeetpost posts what is new there, in each connection's voice and look.
Preview what a link would post
POST/sources/preview
Opens a link and says what yeetpost found there, without saving anything. The link can be a page that lists things (courses, a blog, a changelog), an RSS or Atom feed, a JSON feed or a sitemap. Detection order: RSS or Atom, JSON Feed or a JSON list, a sitemap, a page that advertises a feed (followed), and last a page read by AI.
Returns the kind it found, the name, how many items there are and the newest 5. Use it before POST /sources.
Requires a live key. Rate limit: 20 requests per minute per API key.
curl -X POST "https://api.yeetpost.com/api/v2/sources/preview" \ -H "x-api-key: $YEETPOST_API_KEY" \ -H "content-type: application/json" \ -d '{ "url": "https://herizon.io/courses"}'{ "kind": "feed", "name": "Herizon courses", "resolvedUrl": "https://herizon.io/courses.xml", "itemCount": 24, "items": [ { "title": "Negotiating your salary", "url": "https://herizon.io/courses/negotiating-your-salary", "summary": "A two hour workshop on asking for more.", "publishedAt": "2026-10-20T08:00:00.000Z" } ]}request body (application/json)
The address of a page that lists things, an RSS or Atom feed, a JSON feed or a sitemap. Must be https.
response 200
What was found.
headers: x-request-id, x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset
response body
What the link is. feed covers RSS and Atom; page is a page read by AI.
feed | json | sitemap | page
What the feed or page calls itself, or the host name.
The feed a page pointed to, null when the address itself is the list.
The newest 5.
errors
The url is missing or not a public https address, the link could not be opened (source_unreachable), or no list of items was found on it (source_empty).
Missing or invalid API key.
A test key was used. Sources post for real, so they need a live key.
More than 60 requests in a minute for this API key. Back off and retry.
Something went wrong on our side. Quote the x-request-id when you report it. A failure can happen before the rate limit is checked, so this response carries the request id and nothing else.
The page has no feed and could not be read by AI just now (source_unreadable).
What each code means and the fix: errors.
Watch a link for new posts
POST/sources
Saves a source. From then on yeetpost checks the link every hour, and each new item becomes, per connection, a post written in that connection's voice with a card drawn in its look, put into that connection's queue (mode queue) or saved as a draft (mode draft).
The first check stores every item it finds as already seen and never posts them, except the newest backfillCount (0 to 20, default 0), which are posted. Re-checks never post an item twice.
Send kind push instead of url to make a source your app posts items to, at the pushUrl in the response (see POST /sources/{sourceId}/items).
Limits: 20 sources per account, 10 connections per source, instructions up to 1000 characters, and, per month per account, items written (20 on the free plan, 200 on a paid plan) and page reads, a model reading a page that has no feed (100 and 1000). Over the page reads, a page with no feed answers 429 page_read_allowance_reached. A key scoped to a profile creates sources for that profile and only sees its own.
Requires a live key. Rate limit: 20 requests per minute per API key, shared with GET /sources.
curl -X POST "https://api.yeetpost.com/api/v2/sources" \ -H "x-api-key: $YEETPOST_API_KEY" \ -H "content-type: application/json" \ -d '{ "url": "https://herizon.io/courses", "connectionSlugs": [ "herizon_linkedin" ], "mode": "queue", "instructions": "One post per course, say it is free for members.", "makeCard": true, "backfillCount": 0}'{ "source": { "id": "7d1f0c52-3a8e-4d6b-9c41-0b2e5a9f1c33", "slug": "herizon-io", "name": "Herizon courses", "url": "https://herizon.io/courses", "kind": "feed", "resolvedUrl": "https://herizon.io/courses.xml", "profileId": null, "connectionSlugs": [ "herizon_linkedin" ], "mode": "queue", "instructions": "One post per course, say it is free for members.", "makeCard": true, "status": "active", "lastCheckedAt": "2026-10-27T09:00:04.120Z", "nextCheckAt": "2026-10-27T10:00:04.120Z", "lastError": null, "itemCounts": { "baseline": 22, "new": 0, "writing": 0, "posted": 2, "failed": 0, "skipped": 0 }, "pushUrl": null, "createdAt": "2026-10-27T08:30:00.000Z" }}request body (application/json)
The link to watch. Send this or kind push.
push makes a source your app posts items to instead of a link.
push
A name for the source. Defaults to what the link calls itself.
The connections each new item is posted to.
queue takes each connection's next free slot; draft saves the post for you to review.
queue | draft
Plain words that steer the writing, such as "one post per course, say it is free for members".
Draw an image card in the connection's look when it has example cards.
How many of the newest current items to post now. The rest are remembered and never posted.
The profile the source is for. Every connection must belong to it. A key scoped to a profile can leave it out.
response 200
The source was saved.
headers: x-request-id, x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset
response body
Unique per account, made from the host name. Posts a source makes carry the tags source and source:{slug}.
Null for a push source.
feed | json | sitemap | page | push
The feed a page pointed to.
queue | draft
error means the link failed 3 checks in a row and is no longer checked until you resume the source.
active | paused | error
How many items are in each status.
Where an app posts items, for a push source only.
errors
The body is invalid, a connection slug is not one you can post to (invalid_connection), the link could not be opened or has no list (source_unreachable, source_empty), or the account is at its source limit (source_limit_reached).
Missing or invalid API key.
A test key was used. Sources post for real, so they need a live key.
More than 60 requests in a minute for this API key. Back off and retry.
Something went wrong on our side. Quote the x-request-id when you report it. A failure can happen before the rate limit is checked, so this response carries the request id and nothing else.
The page has no feed and could not be read by AI just now (source_unreadable).
What each code means and the fix: errors.
List your sources
GET/sources
Your sources, newest first, with their state and how many items are in each status. A key scoped to a profile sees that profile's sources only.
Requires a live key. Rate limit: 60 requests per minute per API key.
curl "https://api.yeetpost.com/api/v2/sources" \ -H "x-api-key: $YEETPOST_API_KEY"{ "sources": [ { "id": "7d1f0c52-3a8e-4d6b-9c41-0b2e5a9f1c33", "slug": "herizon-io", "name": "Herizon courses", "url": "https://herizon.io/courses", "kind": "feed", "resolvedUrl": "https://herizon.io/courses.xml", "profileId": null, "connectionSlugs": [ "herizon_linkedin" ], "mode": "queue", "instructions": "One post per course, say it is free for members.", "makeCard": true, "status": "active", "lastCheckedAt": "2026-10-27T09:00:04.120Z", "nextCheckAt": "2026-10-27T10:00:04.120Z", "lastError": null, "itemCounts": { "baseline": 22, "new": 0, "writing": 0, "posted": 2, "failed": 0, "skipped": 0 }, "pushUrl": null, "createdAt": "2026-10-27T08:30:00.000Z" } ], "limit": 25, "offset": 0}query parameters
How many sources to return, 1 to 100. Default 25.
How many sources to skip. Default 0.
response 200
Your sources.
headers: x-request-id, x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset
response body
Unique per account, made from the host name. Posts a source makes carry the tags source and source:{slug}.
Null for a push source.
feed | json | sitemap | page | push
The feed a page pointed to.
queue | draft
error means the link failed 3 checks in a row and is no longer checked until you resume the source.
active | paused | error
How many items are in each status.
Where an app posts items, for a push source only.
errors
limit or offset is out of range.
Missing or invalid API key.
A test key was used. Sources post for real, so they need a live key.
More than 60 requests in a minute for this API key. Back off and retry.
Something went wrong on our side. Quote the x-request-id when you report it. A failure can happen before the rate limit is checked, so this response carries the request id and nothing else.
What each code means and the fix: errors.
Get a source
GET/sources/{sourceId}
One source with its state, last check, last error and item counts.
Requires a live key. Rate limit: 60 requests per minute per API key, shared with PATCH and DELETE on the same path.
curl "https://api.yeetpost.com/api/v2/sources/{sourceId}" \ -H "x-api-key: $YEETPOST_API_KEY"{ "source": { "id": "7d1f0c52-3a8e-4d6b-9c41-0b2e5a9f1c33", "slug": "herizon-io", "name": "Herizon courses", "url": "https://herizon.io/courses", "kind": "feed", "resolvedUrl": "https://herizon.io/courses.xml", "profileId": null, "connectionSlugs": [ "herizon_linkedin" ], "mode": "queue", "instructions": "One post per course, say it is free for members.", "makeCard": true, "status": "active", "lastCheckedAt": "2026-10-27T09:00:04.120Z", "nextCheckAt": "2026-10-27T10:00:04.120Z", "lastError": null, "itemCounts": { "baseline": 22, "new": 0, "writing": 0, "posted": 2, "failed": 0, "skipped": 0 }, "pushUrl": null, "createdAt": "2026-10-27T08:30:00.000Z" }}path parameters
Id of the source, as returned by POST /sources or GET /sources.
response 200
The source.
headers: x-request-id, x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset
response body
Unique per account, made from the host name. Posts a source makes carry the tags source and source:{slug}.
Null for a push source.
feed | json | sitemap | page | push
The feed a page pointed to.
queue | draft
error means the link failed 3 checks in a row and is no longer checked until you resume the source.
active | paused | error
How many items are in each status.
Where an app posts items, for a push source only.
errors
Malformed source id.
Missing or invalid API key.
A test key was used. Sources post for real, so they need a live key.
No source of yours with that id.
More than 60 requests in a minute for this API key. Back off and retry.
Something went wrong on our side. Quote the x-request-id when you report it. A failure can happen before the rate limit is checked, so this response carries the request id and nothing else.
What each code means and the fix: errors.
Change a source
PATCH/sources/{sourceId}
Changes where a source posts (connectionSlugs), mode, instructions, makeCard or its status. Send paused to stop checking and posting, active to resume. Resuming also clears an error and checks again straight away. Send at least one field.
Requires a live key. Rate limit: 60 requests per minute per API key.
curl -X PATCH "https://api.yeetpost.com/api/v2/sources/{sourceId}" \ -H "x-api-key: $YEETPOST_API_KEY" \ -H "content-type: application/json" \ -d '{ "mode": "draft", "status": "active"}'{ "source": { "id": "7d1f0c52-3a8e-4d6b-9c41-0b2e5a9f1c33", "slug": "herizon-io", "name": "Herizon courses", "url": "https://herizon.io/courses", "kind": "feed", "resolvedUrl": "https://herizon.io/courses.xml", "profileId": null, "connectionSlugs": [ "herizon_linkedin" ], "mode": "queue", "instructions": "One post per course, say it is free for members.", "makeCard": true, "status": "active", "lastCheckedAt": "2026-10-27T09:00:04.120Z", "nextCheckAt": "2026-10-27T10:00:04.120Z", "lastError": null, "itemCounts": { "baseline": 22, "new": 0, "writing": 0, "posted": 2, "failed": 0, "skipped": 0 }, "pushUrl": null, "createdAt": "2026-10-27T08:30:00.000Z" }}path parameters
Id of the source, as returned by POST /sources or GET /sources.
request body (application/json)
queue | draft
active | paused
response 200
The source after the change.
headers: x-request-id, x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset
response body
Unique per account, made from the host name. Posts a source makes carry the tags source and source:{slug}.
Null for a push source.
feed | json | sitemap | page | push
The feed a page pointed to.
queue | draft
error means the link failed 3 checks in a row and is no longer checked until you resume the source.
active | paused | error
How many items are in each status.
Where an app posts items, for a push source only.
errors
Malformed source id, an invalid body, or a connection that is not one you can post to.
Missing or invalid API key.
A test key was used. Sources post for real, so they need a live key.
No source of yours with that id.
More than 60 requests in a minute for this API key. Back off and retry.
Something went wrong on our side. Quote the x-request-id when you report it. A failure can happen before the rate limit is checked, so this response carries the request id and nothing else.
What each code means and the fix: errors.
Delete a source
DELETE/sources/{sourceId}
Stops watching the link. Posts it already made stay where they are.
Requires a live key. Rate limit: 60 requests per minute per API key.
curl -X DELETE "https://api.yeetpost.com/api/v2/sources/{sourceId}" \ -H "x-api-key: $YEETPOST_API_KEY"{ "id": "7d1f0c52-3a8e-4d6b-9c41-0b2e5a9f1c33", "deleted": true}path parameters
Id of the source, as returned by POST /sources or GET /sources.
response 200
The source is deleted.
headers: x-request-id, x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset
response body
true
errors
Malformed source id.
Missing or invalid API key.
A test key was used. Sources post for real, so they need a live key.
No source of yours with that id.
More than 60 requests in a minute for this API key. Back off and retry.
Something went wrong on our side. Quote the x-request-id when you report it. A failure can happen before the rate limit is checked, so this response carries the request id and nothing else.
What each code means and the fix: errors.
Check a source now
POST/sources/{sourceId}/check
Opens the source's link now instead of waiting for the hourly check, and returns the items that were not seen before. They are written and posted by the next worker turn, within a minute. A source that is in error and checks fine again goes back to active.
A push source has no link to check. A page source whose page changed but could not be read, because the month's page reads are used, answers 429 page_read_allowance_reached. Each source can be checked once a minute.
Requires a live key. Rate limit: 20 requests per minute per API key, and 1 per minute per source.
curl -X POST "https://api.yeetpost.com/api/v2/sources/{sourceId}/check" \ -H "x-api-key: $YEETPOST_API_KEY"{ "source": { "id": "7d1f0c52-3a8e-4d6b-9c41-0b2e5a9f1c33", "slug": "herizon-io", "name": "Herizon courses", "url": "https://herizon.io/courses", "kind": "feed", "resolvedUrl": "https://herizon.io/courses.xml", "profileId": null, "connectionSlugs": [ "herizon_linkedin" ], "mode": "queue", "instructions": "One post per course, say it is free for members.", "makeCard": true, "status": "active", "lastCheckedAt": "2026-10-27T09:00:04.120Z", "nextCheckAt": "2026-10-27T10:00:04.120Z", "lastError": null, "itemCounts": { "baseline": 22, "new": 0, "writing": 0, "posted": 2, "failed": 0, "skipped": 0 }, "pushUrl": null, "createdAt": "2026-10-27T08:30:00.000Z" }, "newItems": [ { "id": "5b0e8a31-92c4-4f0d-8e17-3c6a1d2b4f55", "title": "Negotiating your salary", "url": "https://herizon.io/courses/negotiating-your-salary" } ]}path parameters
Id of the source, as returned by POST /sources or GET /sources.
response 200
The check ran.
headers: x-request-id, x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset
response body
Unique per account, made from the host name. Posts a source makes carry the tags source and source:{slug}.
Null for a push source.
feed | json | sitemap | page | push
The feed a page pointed to.
queue | draft
error means the link failed 3 checks in a row and is no longer checked until you resume the source.
active | paused | error
How many items are in each status.
Where an app posts items, for a push source only.
errors
Malformed source id, or a push source, which has no link to check.
Missing or invalid API key.
A test key was used. Sources post for real, so they need a live key.
No source of yours with that id.
More than 60 requests in a minute for this API key. Back off and retry.
Something went wrong on our side. Quote the x-request-id when you report it. A failure can happen before the rate limit is checked, so this response carries the request id and nothing else.
The link could not be checked. The source keeps its place and tries again at the next hourly check; after 3 failed checks in a row it goes to error and stops until resumed.
What each code means and the fix: errors.
List a source's items
GET/sources/{sourceId}/items
The items a source has seen, newest first, each with its status, the reason it failed if it did, and the posts it made. baseline items were there when the source was made and are never posted; new items wait for the worker; failed items are tried again at the next check, up to 3 attempts.
Requires a live key. Rate limit: 60 requests per minute per API key.
curl "https://api.yeetpost.com/api/v2/sources/{sourceId}/items" \ -H "x-api-key: $YEETPOST_API_KEY"{ "items": [ { "id": "5b0e8a31-92c4-4f0d-8e17-3c6a1d2b4f55", "title": "Negotiating your salary", "url": "https://herizon.io/courses/negotiating-your-salary", "summary": "A two hour workshop on asking for more.", "publishedAt": "2026-10-20T08:00:00.000Z", "status": "posted", "attempts": 1, "error": null, "posts": [ { "id": "c2f4b7a0-1d3e-4a59-8b6c-9e0f7d1a2b34", "connectionSlug": "herizon_linkedin", "status": "scheduled", "scheduledFor": "2026-10-28T08:00:00.000Z", "url": null } ], "createdAt": "2026-10-27T09:00:04.120Z" } ], "limit": 25, "offset": 0}path parameters
Id of the source, as returned by POST /sources or GET /sources.
query parameters
Only items in this status.
baseline | new | writing | posted | failed | skipped
How many items to return, 1 to 100. Default 25.
How many items to skip. Default 0.
response 200
The items.
headers: x-request-id, x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset
response body
baseline | new | writing | posted | failed | skipped
Why the item failed, or why its card was left out of a post that went out.
sent | scheduled | processing | draft | failed | cancelled | deleted
errors
Malformed source id, an unknown status, or limit or offset out of range.
Missing or invalid API key.
A test key was used. Sources post for real, so they need a live key.
No source of yours with that id.
More than 60 requests in a minute for this API key. Back off and retry.
Something went wrong on our side. Quote the x-request-id when you report it. A failure can happen before the rate limit is checked, so this response carries the request id and nothing else.
What each code means and the fix: errors.
Push items to a source
POST/sources/{sourceId}/items
For apps that want instant posting: sends up to 20 items to a push source (one made with kind push). Each new item goes through the same pipeline as a found one, from new: written per connection in its voice, with a card, into the queue or as a draft. An id the source has seen before is left alone, so retrying is safe.
Requires a live key. Rate limit: 60 requests per minute per API key.
curl -X POST "https://api.yeetpost.com/api/v2/sources/{sourceId}/items" \ -H "x-api-key: $YEETPOST_API_KEY" \ -H "content-type: application/json" \ -d '{ "items": [ { "id": "course-42", "title": "Negotiating your salary", "url": "https://herizon.io/courses/negotiating-your-salary", "summary": "A two hour workshop on asking for more." } ]}'{ "added": 1, "duplicates": 0}path parameters
Id of the source, as returned by POST /sources or GET /sources.
request body (application/json)
Your own id for the item. The same id is never posted twice.
The item's own page, used as the link in the post.
The full text, when you have it. Without it yeetpost reads the item's page.
response 200
The items were taken.
headers: x-request-id, x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset
response body
Items that were new and now wait to be posted.
Ids the source had seen before, left as they are.
errors
Malformed source id, an invalid body, or a source that watches a link and takes no pushed items.
Missing or invalid API key.
A test key was used. Sources post for real, so they need a live key.
No source of yours with that id.
More than 60 requests in a minute for this API key. Back off and retry.
Something went wrong on our side. Quote the x-request-id when you report it. A failure can happen before the rate limit is checked, so this response carries the request id and nothing else.
What each code means and the fix: errors.
Retry a failed source item
POST/sources/{sourceId}/items/{itemId}/retry
Puts a failed item back to waiting with its attempts reset, so the next worker turn writes and posts it again. Only an item in status failed can be retried, or one held back by a burst of more than 20 unseen items (status baseline), which this posts. Once none of the held items is left, the burst leaves attention.
Requires a live key. Rate limit: 60 requests per minute per API key.
curl -X POST "https://api.yeetpost.com/api/v2/sources/{sourceId}/items/{itemId}/retry" \ -H "x-api-key: $YEETPOST_API_KEY"{ "id": "5b0e8a31-92c4-4f0d-8e17-3c6a1d2b4f55", "status": "new"}path parameters
Id of the source, as returned by POST /sources or GET /sources.
Id of the item, as returned by GET /sources/{sourceId}/items.
response 200
The item is waiting again.
headers: x-request-id, x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset
response body
new
errors
Malformed source id or item id.
Missing or invalid API key.
A test key was used. Sources post for real, so they need a live key.
No source of yours with that id, or no failed item with that id in it.
More than 60 requests in a minute for this API key. Back off and retry.
Something went wrong on our side. Quote the x-request-id when you report it. A failure can happen before the rate limit is checked, so this response carries the request id and nothing else.
What each code means and the fix: errors.