> ## 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.

# Keeping your Library answerable

> How a seller reads a document's lifecycle, finds the documents that need attention, fixes one the Library could not read in full, and files several at once.

Your Library is what your storefront agent answers briefs from. The Library is
part of a Storefront account. A Listing account brings its own sales agent, so its
seller rail has no Library row (see [Account type](https://docs.apostra.com/v3/seller-account-type.md)).
This page covers
the upkeep: how to tell where a document is in its life, how to find the ones
that need you, and how to fix or file them. For what the Library is, how
documents inform responses, and the API contract behind it, see the
[Library reference](https://docs.apostra.com/v2/storefront/library.md).

## One lifecycle per document

A document shows exactly one lifecycle state.

| State | What it means |
| - | - |
| **Processing** | The Library is still waiting for the file, or still reading it. |
| **Draft** | It is waiting for your review. Your agent cannot use it yet. |
| **Live** | It answers briefs. |
| **Archived** | It is out of use and excluded from new responses. |

Integrations read the same facts as `materialState` (`draft`, `live`,
`archived`) and `documentStatus` (`processing`, `incomplete`, `ready`,
`archived`).

## Discarding a Draft through the API

Discarding a Draft permanently deletes its stored objects. Confirm with the user
before discarding. Send `save_material` with `materialId`, the current
`expectedRevision`, and `isDiscarded: true`. For several Drafts, confirm once
and make one call per Draft. There is no preview or batch call. Live and Archived
Materials cannot be discarded, and a Draft being processed must finish first.
A stale revision is refused; retrieve the current revision before retrying. In Murph, each Draft requires its own approval before it is discarded.

## When a document needs attention

How completely the Library managed to read a document is separate from that
lifecycle. A Live document the Library could read only part of, or not at all,
**stays Live** — your agent still uses what was read — and reads **Needs
attention** beside its state.

* **Find them all at once.** The **Needs attention** filter lists every Live
  document in that state, so you can work through them instead of scanning.
  It applies to Live documents, so choosing Draft or Archived clears it.
* **Fix one.** Open the row's actions menu. **Try reading again** re-reads a
  linked or connected source. For an uploaded file, open the document and
  replace the file.
* **Or leave it.** A partly-read document is still usable. Nothing is blocked.

Integrations list the same set with
`search(kind: "material", filter: { documentStatus: ["incomplete"] })`. Any
listed status matches, and the filter applies to Live documents, so it cannot
be combined with `materialState` `draft` or `archived`.

## What Library intake notes about each document

If your account is in the modular sales agent beta, Library intake decides what
each document is for as soon as the Library has read it, and keeps that note
with the document. A document plays one role or both:

* **Source.** A document whose rows and fields describe what you sell: rate
  cards, inventory sheets, avails exports and spec sheets.
* **Reference.** A document that stays as you wrote it: media kits, case
  studies and past proposals. It is searched for passages, as it is today.
* **Both.** A media kit or a spec sheet is reference for its prose and may also
  be a source for the figures in it.

Intake decides from how the Library already knows the document: its document
type, the columns of a spreadsheet, the kind of record a history entry
registers, and the document's **purpose** (media kit, case study, spec sheet,
sales deck or one-sheet). It never decides from the words in a file name or in
the text.

For a rate card, intake goes further and reads its prices into your rate card
facts, through the same limits your agent's other catalog changes follow. This
runs only for sellers in the modular sales agent beta: a rate card you upload
before you are enrolled stays as it is, and is read once your account is
enrolled.

* **A rate card that is still a Draft.** Every change waits for an administrator
  to approve it, even a price inside your price band, and the approval says it
  was read from a Draft. A Draft is not yet your own word.
* **A rate card that is Live.** A price change inside your price band applies at
  once. Anything else waits for approval.
* **A rate card you commit yourself.** Previewing and committing a rate card in
  the Library writes its prices directly. When you commit it, the proposals
  intake made from the same file are closed, so the prices are never written
  twice. A closed proposal reads as failed with the reason
  `superseded_by_library_commit`.

Intake never drops a row it cannot turn into a change. Rows the Library could
not read, rows that match no product in your catalog (they stay in the rate card, but price nothing until a product matches), a rate card scoped to one
buyer, and a document that looks like a rate card but is not typed as one each
open a Library request that names them. Intake cannot create a product from a
rate-card row, because a product needs its ad server setup.

For a media kit, intake also reads the audience figures it states, such as "62%
of our readers are 25 to 54". A figure becomes audience evidence on a product,
in the shape the AdCP standard defines, only when the file itself states
everything that shape needs: what the audience is, whether the figure is a
share, an index or a count, its value and unit, who it counts, the baseline
population it is measured against (its system, population id and version) and
the measurement window. Intake never fills in a baseline or a window the file
does not state. A figure that is complete and names one of your products goes
through the same limits as your agent's other catalog changes. Audience
evidence is not a price change, so it is a proposal that waits for an
administrator's approval, whether the media kit is Live or a Draft, and it
names the file it came from. Every other
figure opens one Library request for the document that quotes each figure and
lists what it lacks, such as the baseline or the window, so you can supply it.
Most figures in a typical media kit lack the baseline or the window, so expect
a request. The prose of a media kit stays as written and is searched and cited
as before.

For other documents intake only notes the role. It does not change your catalog,
and your documents are searched and cited exactly as before.

Intake does not guess. When nothing places a document, it opens a Library
request that names the document and its ID and asks you what it is. Answer it
as you would any Library request: upload a clearer copy, or say what the
document is. Setting the document's purpose is enough for the next time the
Library reads it. Two documents with the same name are two requests, and once a
document is placed its request closes.

## Finding documents

Documents are one flat list — never split into sections. Narrow it with the
filters above the list (status, file type, source, category, and your own
storefront dimensions), sort it from the **Name** column header (and
**Updated**, which shows when the Library is wide enough), and switch between the list and a grid. **Clear all** resets
every filter at once.

## Filing several documents at once

Select documents with the checkbox on each row, or the one in the table header
to take everything the page shows. The bar above the list then applies to that
selection:

* Choose a category and select **Apply to N documents**. Nothing is written
  until you apply, and the bar first tells you how many of the selected
  documents already carry a different category and would be refiled.
* **Archive N documents** appears only for Live documents and archives those
  documents; the Library offers an undo. If the selection also contains Drafts,
  it says that they cannot be archived and archives only the Live documents.
* **Discard a Draft** by opening its actions menu and choosing **Review or
  discard Draft**. The review asks you to confirm before it deletes the upload.
* **Cancel** clears the selection.

A document that needs a category — one that went Live without one, for example
from a connected source — is listed by the **Needs a category** filter.

## When a connected source loses a file

A document imported from a connected source (Google Drive, SharePoint or
Confluence) is a copy that Apostra holds. When Apostra loses the file it came
from, it archives the copy, so your agent stops using it, and deletes it 30 days
later. Until then the copy is listed under **Archived**, where the Library
shows **Deleting** and the date in place of its state. Hover over or focus that
date for the reason and the full date.

Four things start the 30 days:

| What happened | Shown as | `reason` |
| - | - | - |
| The file was deleted at its source. | The file was deleted at its source. | `provider_deleted` |
| The file moved out of the connected folder. | The file moved out of the connected folder. | `out_of_scope` |
| Apostra lost access: a permission was withdrawn or the connection's credentials expired. | Apostra lost access to the source. | `access_lost` |
| You disconnected the source. | The source was disconnected. | `disconnected` |

* **The copy leaves use within about an hour.** Apostra archives it on the
  first hourly run after it notices the loss. From then on your agent does not
  read, use or cite it.
* **The file or access coming back restores it.** Put the file back in the
  connected folder, or restore Apostra's access to it, before the date. The
  deletion is cancelled and the copy returns to Live. A copy you had archived
  yourself before the loss stays archived.
* **Only the source can bring it back.** The copy offers no Undo or Restore
  while its deletion is pending, because Apostra would archive it again while
  the source still lacks the file.
* **On the date, Apostra deletes the copy.** Its stored content is purged,
  unless Apostra must preserve it because of a legal hold, a subpoena, or
  another legal or regulatory obligation. The file at the source is never
  touched: Apostra reads from a connected source and never deletes, moves or
  edits a provider file.
* **A date that has passed reads Deletion pending.** The deletion runs about
  once an hour, so a copy can still be listed for a short time after its date.
* **Copies lost before 8 November 2026** got a full 30 days counted from the
  November 2026 release that introduced deletion, not from the original loss.

The date and the reason come from Apostra, not from the Library page. The page
reads them as `connectedSourceRemoval`, an object with `removingOn` (an
ISO 8601 timestamp) and `reason` (one of the four values above), on each row of
`search` with `kind: "material"` and `include: ["browse"]`. The field is
absent when no deletion is pending, and it appears for every seller, whether or
not Delete from Apostra is available. Those rows go to the Library page, not
into the text a chat agent reads, so an agent that calls `search` without
`include: ["browse"]` does not receive the date.

## Adding a document

Adding a document is always deliberate: nothing enters the Library until you
choose a file or drop it on a drop zone.

**Add file** opens a page of its own, with **Back to library** returning you to
the list. Drop files on it, at any time and whatever your Library already
holds, or press Enter to choose them. **Added files** then lists everything you
added, with the review of whichever one is selected beside it — so you work
down a batch without leaving the page:

* A file still going up shows its progress. One that never arrived says so and
  offers **Retry** and **Replace file**.
* A file that lands is a **Draft**. Its row is marked only when it still owes
  you something — **Needs a category** — or once it is settled: **Saved to
  your library**, or **Already in your library**. Selecting the row shows its
  review: the suggested name, category, tags and description, each editable,
  with **Discard** and **Save**. The `‹` and `›` controls beside **Added
  files** step through the files instead.
* Saving or discarding a file opens the next one you have not finished, so a
  batch runs straight through.
* **Save N files** saves every added file that is ready — one whose
  category is already set — at once, without opening any of them. A file that
  still needs a category is not counted and waits for you. A rate card or
  avails sheet is never part of that batch: each is saved from its own change
  preview, because saving it changes live prices or availability.
* A saved file says where it went; a discarded one is deleted and leaves the
  list.

Files you have added are also in the Documents list behind, leading it as
Drafts, so you can finish one later from the list or from chat. Until you save
it, a Draft stays a Draft: your storefront agent can see that it exists, but
never reads, uses or cites it.

The Library splits what you add into slides, pages, or sheets and inspects each
one. Passing inspection makes a unit eligible for reuse; you still decide
whether it is appropriate for a given buyer. Pricing figures stay governed by
your [rate card](https://docs.apostra.com/v2/storefront/library.md#add-a-rate-card) and policy stays
governed by
[AI Business Rules](https://docs.apostra.com/v2/setup/seller-pages.md#business-rules--what-you-accept),
whatever a document says.

Open a spreadsheet and the Library shows its header and first rows, as it read
them from your file, so you can check what your agent will see. This includes
rate cards and availability sheets. A sheet that could not be read shows a
plain placeholder instead, and your original file stays available.

### From a connected source

Every seller account can sync a Google Drive folder, a SharePoint document
library or a Confluence space into its Library. Connect the provider on the
Integrations page and choose what to sync. New files arrive as Drafts, like
any other file you add. A new version of a document that is already Live
updates in place and stays Live.

Google, Microsoft and Atlassian are still reviewing Apostra's connection apps,
so until they finish, signing in can show a warning that the app is not
verified, or your organization's settings can refuse it. If that happens, ask
Apostra support.

### Practise with the example pack

A test or sandbox storefront can add the fictional
[example pack](https://interchange.io/downloads/publisher-onboarding-example-pack.zip)
— a small set of invented documents for a publisher that does not exist. Read
it before you add it, so you know what your agent will be taught: its pages
become reusable units like any other document, and its invented figures are
not quotable. Use it to see the add-and-inspect flow, not to answer a real
brief. A production storefront should add its own material instead.

## Say where a rate-card row applies

Each row of your [rate card](https://docs.apostra.com/v2/storefront/library.md#add-a-rate-card) prices
some of your inventory. Your storefront agent decides which inventory from the
scope columns only: `channels`, `creative_terms`, `publisher_domains`,
`countries`, `advertiser_verticals`, `seasonality`, `signal_tags`,
`placement_tags` and `format_dimensions`. `label` and `applies_when` explain the
row, but the agent never applies a price because of what they say.

* **A scoped row** fills one or more scope columns. It applies to a product that
  matches every column it fills. Within one column, any value can match.
* **A row for everything you sell** sets the `scope` column to `all_inventory`
  and leaves every scope column blank. It applies to every product priced in
  its own currency, so it must name a `currency`. Use it for a storefront-wide
  minimum or default price.
* **A row with no scope** fills no scope column and leaves `scope` blank. The
  agent does not apply it by its `applies_when` text, so it usually applies to
  nothing. The preview flags each such row with the warning `unscoped_row`.
  Fill its scope columns, or mark it `all_inventory` if it really covers
  everything. A `guidance` row is not flagged, because it never sets a price.

The preview rejects:

* a `hard_floor` row with no scope;
* a `scope` other than `all_inventory` or blank;
* `all_inventory` together with a filled scope column;
* `all_inventory` without a `currency`.

The rate-card template, linked from
[Add a rate card](https://docs.apostra.com/v2/storefront/library.md#add-a-rate-card), has the `scope`
column and an example `all_inventory` row. In `save_playbook`, a pricing fact carries the same
marker as `scope: "all_inventory"`, and `get` with `kind: "playbook"` returns
it. `save_playbook` replaces the whole fact list, so send `scope` back with
each fact you keep, or the marker is lost.

## Opening a document

Opening a document takes over the page rather than opening a dialog: its
preview sits on the left and its details on the right, with **Back to
documents** returning you to the list exactly where you left it. A note you
write opens the same way.

The panel on the right is written as the questions you ask about the document,
in that order: **What it is**, **Can your agent use it**, **What it says it
is**, **Where it came from**, and the **Technical record** last, collapsed
until you ask for it. Choosing a page or slide from the filmstrip re-scopes the
panel to that page — a line above the scoped sections says which ones followed
your choice and which still describe the whole document. **Try reading again**
appears where the preview is missing or could not be read, beside the problem
it fixes.

Where a page has already been used — the briefs that cited it, how those
exchanges landed, and the way into Proposal Pass — is not shown here today.
Those records still exist; the exchange that holds the brief is where they will
be read.

## Rehearsing a brief

An active Demo Storefront can rehearse the whole teaching workflow from the
Library, under **Rehearse answering a brief**. It creates no buyer demand and
sends nothing to a buyer. **Add sample documents** adds the fixed sample set,
whose planning rates are not live or buyer-quotable; once every proposed
selling point has a decision, **Open the practice brief** opens the immutable
evaluation turn in Proposal Pass. The server chooses that brief — you cannot
supply or replace it. The API calls this the controlled synthetic evaluation.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.