> ## Documentation Index > Fetch the complete documentation index at: https://docs.apostra.com/llms.txt > Use this file to discover all available pages before exploring further. # Library > The material, responses, and reusable slides your storefront agent uses to sell your inventory. ## Overview The **Library** is everything your storefront agent sells with and learns from, including the proposals you sent. It gives your storefront one place for media kits, decks, one-sheets, case studies, audience cards, spec sheets, seasonal calendars, and responses. [Product marketing](/v2/storefront/product-marketing/overview) becomes the Library: the Material and selling points you already keep there remain available here. This seller Library is not the advertiser creative library that buyers use for campaign creatives. Your Library contains seller Material, responses, and Library requests; it does not contain an advertiser's campaign creative. Before a proposal can use Library material, the selected wholesale product must also be complete: it needs a channel, a canonical URL-free format, and a priced option with currency and delivery type. Product pricing belongs in the product or rate-card flow, never in reusable Library material. If a proposal ends in `needs_clarification`, read the product's request-independent `composerCompleteness.missing` facts and repair them before retrying. The selected pricing option must also match the RFP currency. The Library is not where every seller record belongs. An RFP is a record of demand and stays in the [demand inbox](/v2/storefront/demand-inbox). Your rate card is a typed Library document. Policy lives in [AI Business Rules](/v2/setup/seller-pages#business-rules--what-you-accept). For eligible staging pilots, you can also bring selected content from Google Drive, Microsoft 365, or Confluence Cloud into the Library with a read-only, one-way source connection. The source remains at its provider; the Library keeps workspace-managed copies with visible provenance. See [Connect a source](/v2/storefront/connect-a-source) for provider roots, permissions, supported destinations, limits, and availability. After a provider sign-in, the Library asks you to choose a root, shows a bounded preview of supported and excluded content, then asks you to confirm before it starts indexing. The page shows these steps only when the server has made each one available for your approved pilot. ## Minimum requirements `get_status` lists these Library requirements for a seller storefront. They are advisory: a missing document never stops the storefront agent from answering a brief. * To run the storefront agent, add rate-card facts and a Ready, unarchived sales deck or media kit. * For every modular source that sells guaranteed inventory, add an avails sheet with a committed feed revision for that source. * To promote items, add an AdCP catalogue. When a requirement is missing, `get_status` identifies the document to add. ## Manage a connected source Each connected-source card reports its lifecycle and worker health, the latest successful and attempted sync, the next retry when one is scheduled, the number of available Materials, and any item-level issue from the latest sync. A card can offer **Pause sync**, **Resume sync**, **Sync now**, **Reconnect**, or **Disconnect**. The server advertises the actions that are safe in the card's current state; clients must not infer an action from its status. For MCP App integrations, `library_list_external_sources` returns the card data in `sources[]`. Each source has a revision, `health`, `sync`, `counts`, `notices`, `retainedMaterial`, and the server-advertised `actions`. Follow its `continuation` when present to load another page of sources. Invoke an advertised action with `library_invoke_external_source_action`, using the source ID, its current revision, the action ID, and a unique `clientRequestId`. Treat a revision conflict as a reason to reload the card; do not retry it against an older revision. **Sync now** requests reconciliation from the worker and does not promise that indexing has completed when the tool returns. A file that failed to import is retried a few times automatically and then waits until it changes at the provider; **Sync now** also retries those files, so use it after fixing the cause (for example, restoring access). **Reconnect** starts a new provider consent handoff for the existing source; after the host returns, pass the returned handoff ID and opaque credential reference back to the action tool to finish it. **Disconnect** stops future retrieval. It never deletes provider files or Materials already imported into the workspace: those copies remain readable with their source provenance, subject to the applicable retention policy. Disconnecting removes a provider account only after no other source or picker still uses it. Since 2026-09-07, the Library is available to every seller. ## Add a rate card Add a **Rate card** document to the Library to set the prices your storefront agent may quote. Download the [rate-card template](/rate-card-template.csv), fill in one row per price rule, and upload it as CSV or XLSX. API senders can also push the same CSV or JSON rows through `save_material` with `metadata.documentType: "rate_card"`. If you already maintained a rate card in storefront settings, it is copied to a **Rate card** document in your Library. The Playbook now shows a read-only summary of the current document and links here to edit it. When `save_playbook` or a settings API write changes a price, the Library saves a new version of this document. The Library parses the document before it changes anything. Its preview shows accepted rows, rejected rows with the field to correct, and the rate-card facts that would be added, changed, or removed. After a CSV or XLSX upload finishes processing and its scan is complete, the document is ready to preview. Confirm the signed preview with `save_material` action `commit_rate_card`; an API sender can set `commit: true` on a valid typed-document push. A malformed document never changes live facts. Use `|` to separate multiple hint values in a cell (for example `ctv|olv`), and use `WIDTHxHEIGHT` for each format dimension (for example `300x250|728x90`). `target_price` or `floor_price` is required. A source floor still wins when it is higher than a rate-card price, so the agent never quotes below the source's minimum. Each committed fact records its Library row and revision, which lets a quoted price cite the exact rate-card row. ## Set buyer-specific rates You can add a buyer scope to a rate-card document when a buyer has agreed different rates. Scope the document to an operator domain, a brand domain, or both. A rate card without a scope remains your general rate card. A scoped rate card is available only when the buyer on the request matches its scope. Other buyers, and requests without a buyer identity, use the general rate card and cannot see or cite the scoped document. When more than one scoped rate card matches, the most specific card wins. A rate card scoped to both an operator and a brand takes precedence over a card scoped to one domain. Operator-only and brand-only cards are equally specific; when both match, the most recently committed card wins. For inventory covered by a scoped rate card, its rows replace the general rates. A buyer's flat discount applies only to inventory the scoped card does not cover. Prices always respect the higher of the source cost and any floor set on the applicable rate-card row, so a buyer-specific rate or discount never takes the quote below that minimum. A `hard_floor` also needs structured scope in at least one of `channels`, `creative_terms`, `publisher_domains`, `countries`, `advertiser_verticals`, `seasonality`, `signal_tags`, `placement_tags`, or `format_dimensions`. `label` and `applies_when` explain the row but do not scope a hard floor. The preview rejects an unscoped hard floor, warns when a scoped row currently matches no product, and warns when a matching product's current price is below the floor. Once a hard floor matches, it applies to fixed and auction prices; the agent never quotes that product below the floor. ## Add an avails sheet Add an **Avails sheet** document when you need to update the capacity for one of your modular inventory sources. Choose the source the sheet belongs to, then upload its CSV or XLSX file. The source must already have an active Inventory Feed. The Library checks each row against that source's Inventory Feed before it changes availability. Its preview shows the accepted rows, rejected rows with the reason to correct them, and the feed facts that will be updated. After an upload has finished processing and its scan is complete, confirm the signed preview with `save_material` action `commit_avails_sheet`. A sheet with rejected rows may still commit its accepted rows; rejected rows never change the source's availability. Rows omitted from a later sheet stay live. Include a row in a new sheet when you need to change its availability. Use `preview_avails_sheet` with the document's `materialId` and `sourceRevision`. Its accepted rows, rejected rows, and changes are limited to 100 entries each; use the totals and `truncated` flag when a list is longer. Use `commit_avails_sheet` with the same IDs and the returned `previewToken`. The token is bound to that document revision, its uploaded content, and the feed state that was previewed. If the document or feed changes, preview again before committing. ## Drafts and Save The Library supports **Draft**, Live, and Archived documents. Completed uploads continue to become Live in this release. A later Library update will create a Draft for each upload, suggest a name, category, and description, and ask you to review those details before saving. Drafts stay visible in the Draft filter and Library Gaps as waiting for you. The storefront agent can see that a Draft exists, including its suggestions and gaps, but never uses or cites its content. The later Library update provides the widget controls to Save a Draft as Live or Discard its file. Saving from chat arrives with that update behind a server-enforced web approval: the agent proposes the save and you approve it on our site. A rate-card Draft still uses its normal preview and commit flow before it can change prices. ## Archive and restore a document Archive a document when it should stay in your Library history but should not be available to composition. Archived documents are excluded from the default Documents list and from new proposal composition immediately. They keep their source, revisions, and history. You can restore an archived document at any time. Restoring returns it to the default Documents list and makes it available to composition again. The Library interface will add Archive, Undo, and an Archived filter in a follow-up release; until then, integrations can use `save_material` with `action: "archive"` or `action: "restore"`, and `search(kind: "material", filter: { materialState: "archived" })` lists archived documents. ## Controlled synthetic evaluation An active Demo Storefront can rehearse the teaching workflow from the Library. The controls are available only while that Demo is active. They create no buyer demand and do not send anything to a buyer. 1. Select **Prepare synthetic teaching materials**. The Library adds the fixed six-source sample set. Its planning rates are not live or buyer-quotable. 2. Review every proposed selling point in the Library. The held-out brief stays unavailable until each one has a decision. 3. Select **Open held-out synthetic buyer brief**. The Library opens the exact, immutable evaluation turn in Proposal Pass. The server chooses the brief; you cannot supply or replace it. Proposal Pass then guides you through inspecting the response and its coaching comparison. The Library uses three Page-only MCP contracts. Each requires the signed Library Page permission and an active, unexpired Demo. They are not general chat actions. The sample material comes from the seeded Demo catalogue. The evaluation uses only its confirmed synthetic facts. It never uses ordinary seller Material, Product Marketing content, or Library examples as commercial sources. | Page-only MCP tool | Input | Response and boundary | | - | - | - | | `library_get_evaluation_status` | `{}` | For an active Demo, returns `{ available: true, state, synthetic: true, materialCount, pendingCandidateCount, disclosure }`. The state is `materials_not_loaded`, `review_candidates`, or `ready`. Other seller Libraries receive `{ available: false, reason: "not-demo" }`, so no control is shown. | | `library_prepare_synthetic_materials` | `{ clientRequestId }` | Returns `{ state: "complete" \| "incomplete", materialIds, synthetic: true }`. Retrying continues the same six-source generation. | | `library_start_synthetic_evaluation` | `{ clientRequestId }` | Returns `{ rfpId, turnId, purpose: "evaluation", synthetic: true }` for the server-selected held-out brief. | Custom fulfilment still needs a named person or a Connect follow-up before anything can go live. ## Previewing a document Select a document to open its previewer beside the list on wide layouts and in a sheet on narrow ones. Your search, filters, grouping, and scroll position stay in place, so you can close it with **Escape** or **Back to documents** and continue where you left off. The previewer shows the document or selected page, its category, and summary facts. Use the category control there when you need to change how your storefront agent classifies the document. Select **Edit** for the document's tags, reuse and inspection facts, linked usage, and other detailed controls. ## How documents inform responses Once a document is processed and remains unarchived, the agent can retrieve and cite its relevant passages directly. There is no selling-point or case-study review queue, and no Accept or Reject control for prose. To stop a document informing future responses, archive it; its history remains available. The Library still proposes changes when a document contains structured information that belongs elsewhere, such as a format specification, signal, business rule, or seller identity. Those proposals use the review flow for their destination. Prices come only from a rate card, never from prose. ## Document categories Set a document category so your storefront agent can decide when to use it: **Sales deck**, **One-sheet**, **Case study**, **Response**, or **Specification sheet**. Topics, audiences, and verticals are set separately; changing a category does not change those tags or the source file. Existing Material and new uploads start as **Uncategorized** until you choose a category. The Library does not guess a category from the file name, source, or extracted content. Choose **Uncategorized** again to clear a category. The Library groups documents by the Material-only Category dimension. Documents without a Category label appear last under **Uncategorized**. You can switch to the grid at any time. The Library's **Category**, **Topic**, **Audience**, and **Vertical** chips are storefront dimensions. Category appears first. Choosing one sends a server-side label filter, so every loaded page belongs to the same selection. Values in one facet are alternatives; values from different facets must all match. Category and file-type filters show counts for the currently loaded result rows. They work together with search and grouping, and each filter can return to its own **All** option without clearing the other one. If more documents are available, the Library keeps **Load more documents** visible even when the loaded rows have no match. After all rows are loaded, a combination with no matches shows an empty state with a clear-filters action. All Material appears in one **Documents** list. Opening a document is where you browse its pages or slides, previews, and inspection details. Rate-card and policy documents can remain Material sources for extraction and provenance, but assigning a category does not move their governed facts into the reusable Library. Canonical pricing remains in the [Rate card document](#add-a-rate-card), and policy remains in [AI Business Rules](/v2/setup/seller-pages#business-rules--what-you-accept). Existing pricing-safety rules still block reuse of a unit that contains a commercial figure. ## Responses and pairs The Responses section lists materials paired to the brief they answered, along with imported historical proposals. Each entry keeps its saved name and version date and names the brief it answered when one is linked. It remains available when other Library documents change. When you open a composed response for seller review, a supported block can show where it came from, for example *From Travel + Leisure media kit, slide 6* or *From Rate card, row 14*. These citations are seller-review information: buyer deliveries never include them. If the cited revision has been removed, the response says **Source no longer available** rather than guessing a replacement. If a cited document has a newer revision, the Responses list and the composed response show that the document has changed since the response was sent. You can choose **Re-run brief** to create a new response turn against the saved brief. Archiving a cited document does not make its saved citation unavailable; only a removed cited revision does. A **pair** holds that brief, the response, your commentary, and the commercial outcome recorded for the exchange. Choose the uploaded Library document that holds what you sent; attaching it saves it as this brief's response. Briefs that already have a response are unavailable rather than silently replaced. For integrations, Material reads report `materialKind` as `document` or `response`. Search with `filter.materialKind: "response"` to return only Materials paired to a brief or imported as historical proposals; use `document` to return Materials that have not been saved as a response. Material browse also accepts `filter.hasUnits`: `true` returns Materials whose current active rendition has at least one page or slide, `false` returns those with neither, and omitting it returns both. You can also start from an eligible row in the [demand inbox](/v2/storefront/demand-inbox). Choose an uploaded Library document after you add the file to the Library. To save an uploaded Library document as a response, open it in the Library and choose **Save as a response**. Direct file upload in the Demand Inbox is out of scope. Use **Import historical brief** from an uploaded document's detail view in the Library when the brief is not recorded yet; imported briefs remain historical reference records. A historical proposal with no brief stays in Responses as a standalone shape example. Your grade and feedback are commentary on the pair. When you **endorse** a pair, you mark its response as a good answer to that brief. An endorsed pair is an evaluation case: rerun the brief and compare the result with the endorsed response. The outcome on the pair remains the record of what happened commercially. ## Reusable slides Uploaded decks, one-sheets, and spreadsheets yield reusable slides, pages, or sheets. Each starts as not reusable and can stay in the Library as a historical record without being available to add to a response. Only individual slides, pages, or sheets can be made reusable; a whole document or structural container cannot. A clean inspection makes one page, slide, or sheet eligible for reuse. It does not mean that unit is appropriate for every buyer. Review each unit and leave buyer-specific, expired, or otherwise unsuitable content off. The control updates automatically when a pending inspection finishes; you do not need to reload the Library. Every reusable unit is checked for pricing. A unit with pricing is marked and cannot be made reusable until the price is removed. Keep current prices in your [Rate card document](#add-a-rate-card), then upload the price-free page, slide, or sheet. Figures in reusable units can reserve the layout for a price, but the value that renders comes from Rate Card. This keeps a stale or buyer-specific number out of a response. ### How a page is inspected Each slide or page of an uploaded PDF or deck carries the state of its own inspection, and the document carries a summary of all of them. You see these states on the unit and in the `document_inspection` summary of a Material rendition: * **Preview**: whether a faithful picture of the page exists. Library combines the stored `preview_state` with the source and processing state so that it is explicit when previewing is unsupported or unavailable. `ready` when the page was rendered, `partial` when only some of the document could be rendered, `failed` when rendering was attempted and did not complete, `unsupported` when this source cannot produce a faithful page or slide preview, `unavailable` when a supported file was not inspected, and `pending` while inspection is queued or running. * **Reading** (`semantic_state`): whether the page's text and layout were read. `ready`, `partial`, `failed`, or `unsupported` for a file type that cannot be read; `not_started` until reading begins. * **Scan** (`scan_status`): whether the whole page was scanned for commercial figures, including numbers that appear only inside images. `scanned` when the whole-page scan ran, `not_scanned` when it did not, `not_applicable` for a unit that has no page image, such as a spreadsheet sheet. * **Pricing safety** (`pricing_safety`): the outcome of the scan. `safe` means the whole page was read and no commercial figure was found; `contains_pricing` means one was found; `unknown` means there is no page-by-page conclusion. Read it with the preview state: on the document summary, `unknown` with `preview: unavailable` means whole-page inspection has not been attempted for this storefront yet, while `unknown` with `preview: failed` or `partial` means it was attempted and did not conclude (the render was cut short, rendering or reading failed, or the whole-page scan did not run). A unit with no value here was never inspected page-by-page and falls back to the text scan of the file itself. A unit whose safety is `unknown` or `contains_pricing`, or whose preview or reading is incomplete, cannot be made reusable until the page is inspected cleanly. Spreadsheet sheets and historical units without page-level inspection fields can still be eligible when the canonical source text scan is clean. After a private upload finishes, new PDF and PowerPoint files move from `pending` to their final inspection state in the open Library without a manual reload. If the private upload itself does not finish, the document says **Upload incomplete** instead of presenting that state as an inspection. Choose **Retry upload** and select the original file again. The retry creates a new immutable source revision for the same Material; it does not create a duplicate Library document. PDFs and PowerPoint files saved before whole-page inspection was introduced were not changed or backfilled, so they can remain `unavailable`. Open one of those files and select **Retry inspection** to queue its current source revision. The retry is limited to that Material in your seller account and is safe to repeat if the first request's result is unclear. It does not change or delete the original file. When a reusable slide appears in a response, it is a Library block with its source named. You can turn Library blocks on or off and reorder them before sending. ## Add material Select **Add material** at the top of the Materials section in the Library to upload a PDF, PowerPoint (`.pptx`), Excel (`.xlsx`), CSV, PNG, JPEG, GIF, or WebP file. The Library checks the file type before it starts the private upload, then processes the new Material and shows its pages or slides here. A file type the Library cannot read is refused before it is uploaded. Uploaded decks and one-sheets show their reusable units after processing. A unit with pricing is marked and stays unavailable for reuse; clean units can be toggled reusable from the Library. ## Notes Not everything your storefront agent needs is in a file. Select **Add a note**, give it a short title, type the text, and save. You can also tell your storefront agent in chat; it saves the same kind of note. A note is a Library document. Your agent can cite it the way it cites a file. Open a note to read its text and see who wrote the current version and when. Notes written from chat identify your storefront agent as the author. Notes keep their earlier versions and can be archived and restored like other Library documents. Prices never come from a note; keep them in your [rate card](/v2/setup/seller-pages#rate-cards--how-you-price). ## How your agent uses the Library When a Material search requests `evidence_matches`, it can return up to 24 current readable matches from 48 candidates. Each match names its Material source revision, rendition, unit, exact source locator, and the result receipt. The search result does not include source text for model use. ### Matching rendered previews When your agent reads a Material with `get` and `include: ['repeats']`, `included.exactRenderedPreviewGroups` can identify separate readable units with the same rendered preview. This helps you review repeated rendered pages or slides without treating them as the same Material. The comparison includes only complete previews for whole units. It is `same_rendered_preview` only when the stored preview content digest and rendering configuration digest match in one rendering/configuration domain. Each occurrence remains separate, with its own Material, source revision, rendition, unit, and document order. The read checks your current permission for every occurrence before it groups or counts anything. Seeing an occurrence does not make it available for model use or reuse. Results are bounded: use each group's `returned` and `truncated` values, and the overall `truncated` value, rather than assuming the response lists every occurrence you can read. A matching rendered preview is not a claim that two units have the same meaning, source, or approved-template status. **Shaped by** is seller-facing provenance. On your Proposal Pass and the HTML, PDF, and PPTX previews you review, it names the endorsed example your agent followed from your own demand-inbox records, with its brief subject, pair id, endorsement date, and one sentence on why it fit. It is never included in what a buyer receives. If no endorsed pair fits, it says so and composes from Library material instead. Pairs are evidence from one buyer relationship. For a different buyer, the agent receives only the structure-only shape projection: its allowlisted block kinds, roles, and order. It does not receive the other buyer's name, contacts, brief, budget, negotiated rates, commentary, or response text. A pair follows its brief's retention. If the brief is deleted or a buyer asks for deletion, the pair and its shape projection stop shaping later responses. An earlier response keeps only a tombstone with the pair id and date, not its content. ## Library requests A **library request** records a gap the storefront agent found while answering a brief, such as a case study for a channel or vertical the Library does not cover. The agent files one request for each gap, and the response states the honest absence instead of inventing a block. **Add material** is the direct path when you have material to add. You can also close a specific Library request by uploading the missing file from that request or telling your storefront agent what to use. An uploaded file can provide reusable-slide candidates. Material you provide in chat is marked as your word rather than a document and feeds composed blocks; it does not become a slide. The request records which path closed it. ## The Library Page Your storefront agent opens the Library Page when you ask to see or manage your Library. The page opens as one Documents list grouped by document category when at least one document has a category, and you can switch to a grid or choose a different grouping. It shows your documents and decks as files. You can search, different grouping. You can search, filter documents by category, file type, or storefront dimensions, group rows by topic, audience, vertical, or source, and load more rows as you go. Opening a document lets you change its category and shows its pages or slides with their preview, reuse, and inspection state, and any repeated previews found elsewhere in your Library. The Usage view lists the sent responses that used a page or slide; from there you can open the Proposal Pass for that response. Responses and open Library requests stay secondary views, and the Upload control on a request adds the missing file directly. Cards and rows now start with a file-type thumbnail. A visual render replaces it when one is available. While a render is processing, the thumbnail has a **Preview pending** marker. When there is no usable visual render, its thumbnail shows **Preview unavailable**. If an available image cannot load in your browser, the file-type thumbnail remains and the card says **A current preview could not be loaded**. ## Related Review demand, attach what you sent, and endorse a pair. Add Material and inspect its units. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.