pull_content
Pull licensed creator content from a specific pocket by ID. Use this tool when an AI agent needs to retrieve verified, provenance-tracked content for generation, RAG, and inference use. Training use requires a separate training license — see training_use in the agreement terms. Do NOT use for browsing or discovery — use search_pockets or list_pockets instead. Requires a valid Bearer token for authentication; unauthenticated requests return HTTP 402. Successful pulls trigger a metered charge at the pocket's own price (quoted as owner_price on the receipt; $0.0025 platform default only when a pocket sets none) and the transaction is logged for creator royalty distribution. The pocket_id parameter is a 24-character hex string identifying the specific content pocket to pull from. Returns the full content payload with provenance metadata including creator attribution and license terms. Every call returns a receipt of the same shape (receipt_id, outcome, reason, amount_paid, terms, content_hash, and agent_count / agent_work_count: how many times this agent has accessed the owner's account and this work, this call included) with a public verify_url: on success under 'receipt' in the result (outcome 'delivered'), on an HTTP 402 refusal under 'receipt' in the error body (outcome 'refused', reason 'registration_required' when no valid API key is presented, 'payment_required' when the wallet balance is too low or the card charge fails). A pocket whose rights holder has closed its catalog is refused for every caller, with or without a key, as a normal result (not a 402) with reason 'catalog_closed', owner_price null and the receipt under 'receipt'; nothing is delivered or charged. A listing-only pocket (delivery 'listing' in search results) has no file: its pull is charged the owner's per-pull price like any other and returns delivery 'listing' with 'content' set to the listing object {title, isrc, owner, terms, link} and no download URL. content_hash is the sha256 hex of the delivered 'content' field only: a string is hashed as its UTF-8 bytes, an object as UTF-8 JSON with sorted keys and no whitespace.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Optional natural language focus query used to narrow or contextualize the returned content within the selected pocket. | |
| pocket_id | Yes | The 24-character hex identifier of the content pocket to pull from. Obtain this from search_pockets or list_pockets results. |