Add posts by URL

Requires `posts:write` (opt-in when the key is created). Adds up to 100 post URLs to the team the same way **Add New** does in the Siftsy app: each accepted link reserves one MAP or Ad Hoc credit (5 with `capture.fullRead`), creates the post, and queues it for processing. Links already on the team are `skipped` (never charged); links on an unsupported host are `rejected` up front (never charged). Responds `202` with a `ContentJob` and a `Location` header. Poll `GET /content/jobs/{jobId}` until `status` is `completed`, `partial`, or `failed`, honoring `Retry-After` / `meta.pollAfterMs`. Posts become readable through `GET /posts` as they finish processing. Order of operations inside the request: validate links → resolve the target team → resolve `collections` → replay check → dedupe against the team's posts → fund check for the whole batch → reserve + create each post (`status: fetching`, `addedVia: api`) → queue. The per-link outcome (`accepted` / `skipped` / `rejected`) is therefore final on the `202`; only processing remains. See the Adding content guide for the post lifecycle and when credits are consumed or refunded. - `collections`: attach the posts to existing collections by `id`, or by `name` — an exact (case-insensitive) match on an active collection is reused, otherwise a new campaign is created. A name that matches more than one collection returns `409 collection_name_ambiguous` with the candidate ids. - `tags`: free-form content tags (strings), merged onto the posts. - `teamId`: for Enterprise keys only — a sub-team of the key's enterprise to add to (credits are reserved on that sub-team). - `credits.source`: `auto` (MAPs first, then Ad Hoc) or `adhoc`. Identical requests within the retention window return the existing job (`200`, `meta.replayed: true`) instead of charging twice. When the whole batch cannot be funded, nothing is created and the response is `402`. Rate class `content_add_posts` (10 / minute, 200 / day per key).

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

OR
X-Api-Keystring
API Key authentication via header

Request

This endpoint expects an object.
teamIdstringOptional

Enterprise keys only — a sub-team of the key’s enterprise to add to

collectionslist of objectsOptional
tagslist of stringsOptional

Content tags to merge onto the posts (leading # is dropped)

creditsobjectOptional
captureobjectOptional

Response

Identical request replayed; existing job returned (meta.replayed: true)

dataobjectOptional
metaobjectOptional

Errors

400
Bad Request Error
402
Payment Required Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
429
Too Many Requests Error