Skip to navigation

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