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

# Ask Murph

> Murph is the in-product assistant that helps storefront operators set up, merchandise, and run their storefront

Murph is the assistant built into Apostra platform for storefront operators.
It works alongside you in chat to set up your storefront, connect inventory
sources, compose products, and surface the analytics you need to negotiate and
sell. Murph is available to every storefront account — open the **Ask Murph**
panel from your storefront workspace to start a conversation.

The chat shows **You are interacting with an AI agent.** above the message box
before you send your first message. The line remains visible throughout the
conversation.

<Info>
  This page is written for storefront operators. Buyers have Murph too — with
  buyer-side powers, a buyer Dashboard, and the same **Your requests** list —
  and can also work directly through the
  [Buyer API](/v2/buyer-introduction) and the Merchandising Agent.
</Info>

## What Murph helps with

| Area                     | What Murph does                                                                                                                         |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| **Storefront setup**     | Walks you through onboarding, captures your [business profile](/v2/object-guides/storefront), and gets your storefront ready to sell.   |
| **Connecting inventory** | Sends you to the secure forms for ad servers like Google Ad Manager, FreeWheel, SpringServe, and AdsWizz, then verifies the connection. |
| **Setup documents**      | Reads uploaded brand books, media kits, rate cards, and operating instructions so you don't have to paste them into chat.               |
| **Merchandising**        | Helps compose products and tune negotiation defaults using your recent storefront outcomes.                                             |
| **Seller analytics**     | Surfaces win rate, buyer asks, top products, and recommended negotiation posture so you can see what's working.                         |
| **Sandbox testing**      | Runs and reports on [sandbox test plans](/v2/features/sandbox) so you can validate behavior before going live.                          |
| **Shared rooms**         | Turns a conversation into a [shared room](/v2/features/murph-shared-rooms) teammates in your organization can join.                     |
| **Diagnostics**          | Opens source health, ADCP Calls, test runs, and change history so product questions can be answered from live evidence.                 |

## Connecting your ad server

Murph guides you through connecting an upstream inventory source rather than
asking you to hand over secrets in chat. For password- or token-based ad
servers, Murph links you straight to the secure credential form, waits for you
to submit, then runs a connection test to confirm the source can authenticate.

For Google Ad Manager, no password is needed at all: Apostra creates a
service account dedicated to your account, and you grant that service-account
email access inside your GAM network. Before walking you through the grant, Murph explains
what access Apostra needs, what it will not do, and what the granted role
allows — and asks for your explicit consent first.

<Tip>
  Apostra stores only non-secret display fields for a connection. The upstream ad
  server holds the encrypted secret and mints short-lived tokens as needed. See
  [Storefront onboarding](/v2/setup/storefront-onboarding) for the full
  connection flow.
</Tip>

## Uploading setup documents

You can upload PDFs, decks, spreadsheets, images, and text documents during a
conversation. Murph summarizes them into structured facts instead of copying
the raw contents back, so it can reference your brand book, rate card, or
do-not-air list in later turns without re-reading the whole file.

For brand books, Murph can identify brand-manifest candidates — name, website,
colors, fonts, tone, tagline, and disclaimers — and help you draft or compare
the fields that map into a `brand.json`. When you upload or link to canonical
brand artifacts, Murph compares what it learns against the current AAO
brand.json state and calls out new information, changed values, conflicts, and
assets that still need public URLs. For logo images, Murph can upload the asset
to AAO for review; pending uploads are tracked but are not used in `brand.json`
until AAO approves and lists the public `/assets/brands/...` URL. Murph can
preview the exact `brand.json` update and, after you confirm it, publish it to
AAO for your verified storefront brand domain.

For media kits, advertiser policies, and insertion orders, the offline scan also
produces separate setup candidates when the document supports them: a business
profile patch, complete acceptance-policy markdown (including every category
the document says needs review), and URL-free AdCP 3.1 creative-format
declarations. Murph presents each candidate for confirmation. Nothing is
silently applied, and confirming one candidate does not approve the others. If
a policy is incomplete or too long for complete inline review, Murph marks it
as not writable and sends you to the AI Business Rules page and original
document instead of applying partial text.

### File attachments

Murph accepts file attachments on a per-turn basis, with these limits:

* Creative media files (MP4, QuickTime, MP3, WAV, and M4A) and ZIP creative
  bundles are accepted up to **50 MB** decoded size. Every other attachment
  type is capped at **5 MB** decoded size.
* The total decoded payload across all files on a single turn is capped at
  **50 MB**, even when you attach more than one file.

Media uploads are treated as transient creative assets for the current turn.
Murph hands them to creative tools through `murph-attachment://` placeholders.
For MP3, WAV, and M4A audio up to **7 MB**, Murph also transcribes the upload so
you can talk through a request or ask about spoken content; the transcript is
treated as untrusted user content. Transcription uses Gemini 3.5 Flash through
Apostra's governed Vertex AI connection; it does not use an uploader-supplied API
key. Larger audio files remain available as creative assets but are not
transcribed inline. The raw media bytes are never decoded as text.
Attachments are not persisted to conversation history, so if a follow-up turn
needs the same file, attach it again or first write it into durable Apostra
state through a creative tool.

### How much of a document Murph reads

The size limits above are about what you can upload. Separately, there is a
limit on how much of a document's extracted text Murph carries into a single
turn, along with the other context it assembles for that turn — the page you are
on, your open requests, and the state of the conversation.

Each of those is bounded at 24,000 characters, which is above the largest
context Apostra produces in practice, so a normal document, page, or
conversation fits whole. Murph prioritizes what it extracts, so if a very long
document does exceed the limit, the structured setup facts it found — brand
fields, acceptance-policy categories, creative formats — are kept ahead of
lower-priority detail.

<Note>
  If Murph does hit that limit, it tells you its view of the content is
  incomplete rather than answering as though it had read everything. If you see
  that, ask about a specific section, or split the document and upload the part
  you want reviewed.
</Note>

## When Murph says it did not find something

A "no" from Murph is scoped to what it actually searched, and it says which
that was — "nothing in the documentation I searched", or "no request recorded
on this account". It is not a statement that the thing does not exist. Murph's
tools reach the product documentation, your account, and your requests; plenty
of the answer space sits outside them.

So when Murph reports not finding something, read it as *"not here"*, not
*"nowhere"*. If the answer might sit somewhere Murph cannot reach, it says so
and points you at who could confirm it — another part of the product, or Apostra team. It points you at someone who can *check*, which is not the same as
promising they already have the answer. Asking Murph to file a request is
always available if you would rather have a person look.

## Usage availability

Murph does not stop normal chat at a 24-hour token allowance. An unusually high
amount of automated or runaway usage can still trigger a temporary safety
pause. If that happens, Murph shows when you can try again. Gemini-backed chats
also keep tool instructions compact instead of repeating expanded instructions
during multi-step work.

## Stopping a response

While Murph is working on a turn, a **Stop** control appears in the composer.
Pressing it ends the turn right away instead of making you wait for it to
finish — useful when a request is taking longer than you want, or when you'd
rather rephrase and ask again.

Stopping halts Murph at the next step in its work. A step already underway — a
model response or a tool call that is mid-flight — runs to completion; Murph
stops before starting the next one.

<Warning>
  Stopping does **not** undo work Murph already completed on that turn. If Murph
  had already made a change before you pressed Stop — for example, applying a
  setting or saving a value — that change stands. Stopping only prevents the
  remaining steps. The reply on a stopped turn says so. To control a durable
  write *before* it happens, use [Murph
  confirmations](/v2/setup/murph-confirmations), where protected writes wait for
  your explicit approval.
</Warning>

A chat response for a halted turn includes `stopped: true`. It is omitted on
turns that run to completion.

## Seller analytics and merchandising

Ask Murph for seller analytics and it can show your recent performance — win
rate, buyer asks, top surfaced products, and the commercial outcomes attributed
to your discovery runs. Murph turns that history into directional negotiation
guidance and a recommended posture, and the same recent outcomes can tune the
Merchandising Agent's negotiation defaults when composing products.

Your human operating instructions always remain authoritative over these
historical defaults — Murph's analytics inform the suggestion, they don't
override your rules.

## Your requests and support

An **ask** is anything you are waiting on Apostra for. Ask Murph to show your
current requests to see them in one view, grouped by kind:

* **Support** — problems, confusion, and blockers. Active support asks can show
  when the next update is due and whether you have confirmed that you are still
  blocked.
* **Product** — ideas and feature asks tracked for product review. Tracking an
  ask is not a commitment to build it. When you state a clear product idea,
  Murph adds it to this list automatically; you do not need to file a separate
  support ask or repeat the request. If the same ask is already open,
  Murph keeps the existing item instead of creating a duplicate. If product
  tracking is not available for your account or Murph cannot verify the write,
  it says that the ask was not confirmed instead of claiming it was recorded.
* **Supply (buyer accounts only)** — seller, property, and channel inventory a
  buyer wants Apostra to carry.
* **Integration** — a counterparty we do not connect to yet, named by vendor.
* **Commercial** — pricing, terms, billing, and rate-card exceptions. Kept
  apart from support so a commercial question is not queued as an outage.

### What each status means

Every ask uses the same short status list. Open statuses describe Apostra’s progress. **Done** and **Closed** describe Apostra’s outcome only; your confirmation remains separate.

| Status        | What it means                                                                                                       |
| ------------- | ------------------------------------------------------------------------------------------------------------------- |
| `received`    | Apostra recorded the ask.                                                                                           |
| `accepted`    | Apostra acknowledged or planned the ask, without promising a delivery date.                                         |
| `in_progress` | Apostra is actively working on the ask.                                                                             |
| `done`        | Apostra verified that the requested change or customer-visible result is live and is waiting for your confirmation. |
| `closed`      | Apostra recorded an explicit no-change or cancellation outcome; you can acknowledge or dispute it.                  |

Each ask also includes a customer-facing label and explanation. Internal workflow states, ticket names, and engineering identifiers are not shown.

For support, product, and commercial asks linked to delivery work, closing an issue or merging a pull request is not enough. The ask reaches **Done** or **Closed** only after the explicitly linked work appears in a verified production release. It then remains in your recent history for 90 days with the release version and date, what changed or why no change was made, what you should do next, and delivery status. Supply and integration asks can also finish from their own customer-visible live-state evidence.

### Reading your asks from the API

Your own agent or integration can read the same list directly:

```http theme={null}
GET /api/v2/asks?limit=10
```

The response is read-only and scoped to your account from the API key you call
with — there is no customer parameter, and you can only ever read your own
asks. Each item carries `statusKey` (the values above) plus `statusLabel` and
`statusDescription` for display, and a call returns at most 25 asks alongside
`hasMore`. When `hasMore` is true, pass `nextCursor` back as `cursor` to read
the next page. See the
[buyer](/v2/buyer-api-reference) and [storefront](/v2/storefront-api-reference)
API references for the full shape.

On `/mcp/v3`, use `search` with `kind: "ask"`, then pass the returned opaque id
to `get` with the same kind. Record your own answer with `save_ask`, the opaque
id, and `requesterState`; ask content and Apostra's status remain read-only.

When you explicitly ask for a person, Murph prepares the support ask first — it
does not make you repeat the request or wait through diagnostics. For a blocker
without a direct human request, Murph uses available diagnostics or safe
recovery steps before preparing the ask. Either way, customer-authored filings
wait for your approval before they create team-visible work.

The ask content and Apostra status are read-only and scoped to your account.
Tell Murph whether the requested outcome happened, you acknowledge a no-change
answer, you are still blocked, or you want to withdraw the ask. Internal
routing identifiers are not shown. If one source cannot be read, Murph labels the view
as partial — the API reports that source in `unavailableKinds` — instead of
saying that you have no requests. A bounded result may also say that it is
showing the first set of requests rather than implying the list is complete.

Every kind shows open asks plus explicitly fulfilled asks from the 90-day recent
history described above. During the transition from the older support ledger,
some existing support asks may not yet include the next-update or still-blocked
details, but every returned ask has an opaque id.

### Compatibility payload for older clients

Older chat clients receive support-ask filing results in fields named
`escalated` and `escalation`. These are deprecated wire-format keys, not a
second customer object or lifecycle. Render the object as an ask, and check
`linearVisibility` before rendering any legacy Linear reference.

```json theme={null}
{
  "escalated": true,
  "escalation": {
    "linearIdentifier": "MURPH-123",
    "linearUrl": "https://linear.app/scope3/issue/MURPH-123/example",
    "linearVisibility": "visible",
    "slackPosted": true,
    "severity": "medium"
  }
}
```

`linearVisibility` can be:

| Value             | Meaning                                                                                                                                            |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `visible`         | `linearIdentifier` and `linearUrl` may be shown to the caller.                                                                                     |
| `hidden_for_role` | Linear exists, but the current caller is not allowed to see the Linear reference. Treat `linearIdentifier` and `linearUrl` as hidden, not missing. |
| `unavailable`     | Linear was not configured, failed, or did not return a reference.                                                                                  |

After Murph files it, ask Murph to show your current requests. In Apostra,
the same tracker is available from the **?** menu and opens directly without
filing another chat turn. In Slack, ask Murph for the status in the thread where
you filed the request.

## Working in the Dashboard

Ask Murph includes dashboard surfaces so you can review your state without
leaving Murph.

Sellers can open **Dashboard** from the storefront rail, or ask Murph for seller
analytics. It opens the current seller analytics widget in chat, showing recent
performance, buyer brief outcomes, delivery, and merchandising guidance from
the same storefront analytics surface.

Buyers see a separate **Dashboard** view with Overview, Reporting, Activity,
and Creatives, plus an advertiser selector to
scope each tab to a single advertiser. Buyers also get a **Browse storefronts**
item in the sidebar that opens the full marketplace browse page inside the
Murph shell.

## Working in Diagnostics

Ask Murph also includes a **Diagnostics** view under the **Help** menu. Use it
for the storefront-wide change history and protocol-call evidence behind a
product or setup question.

The **Calls** tab is an account-wide feed of recent ADCP protocol activity for
connected sales agents. Do not treat an unfiltered account feed as evidence for
one Source. For a specific Source, follow **Agent → Inventory sources → \[your
Source] → Open full diagnostics → Calls**. If you need a direct link to the
account Diagnostics Calls view for that exact Source, include its source ID:

```text theme={null}
https://app.apostra.com/<account-id>/murph?view=diagnostics&diagnosticsTab=debug-calls&debugSourceId=<source-id>
```

For an actionable health verdict and a no-spend `get_products` test against a
third-party sales agent, open the Sales Agent Diagnostics app instead:

```text theme={null}
https://app.apostra.com/<account-id>/murph?view=chat&askMurph=open_feature&feature=source-health
```

When you ask about a sales-agent source in Slack, Murph provides the same link
as an **Open sales-agent diagnostics** button because Slack cannot render the MCP
app inline.

For the full workflow, see [Diagnose third-party sales agents](/v2/storefront/inventory-sources/diagnostics).

## Murph in Slack

Apostra can invite Murph into a shared Slack channel with your team. A channel
is connected to exactly one account; once connected, Murph answers
account questions there with that account's data.

In a direct message, Murph selects an account only when the domain in your
Slack email exactly matches one active account's approved domain and you
currently have an active seat on that account. Personal-email domains,
unapproved or inexact domain matches, missing or revoked seats, and multiple
eligible accounts do not select an account. If Murph cannot verify those
conditions, including when an access check is unavailable, it fails closed and
does not use account-specific data until your access can be verified.

Tag `@Murph`, use `/murph`, or send Murph a direct message when you want a
response. In a channel message, the leading mention is the addressee: a message
that starts by tagging another person stays ambient even if it mentions Murph
later. You can include a supported file with an `@Murph` request or in a DM for
Murph to review. A top-level file uploaded to the shared channel without a
caption is treated as ambient channel content, so Murph stays silent. Ordinary
replies between people stay ambient too, even when they include account-specific
troubleshooting details.

Murph uses the Slack thread as the durable conversation. When a follow-up is
posted as a new top-level message instead of inside the original thread, Murph
also reads a small window of nearby channel messages so it can understand what
the follow-up refers to. Those nearby messages are context only; they never
change which account or tools the speaker is allowed to use.

That thread and channel window is bounded, the same way document and page
context is (see [How much of a document Murph reads](#how-much-of-a-document-murph-reads)).
A long thread fits whole. Two things can make the view partial: the thread's
text exceeding the window, or the thread having more replies than Slack returns
in one read (50). In either case Murph says its view of the thread is incomplete
instead of inferring what it cannot see — so if an early message matters and
Murph has flagged the thread as partial, paste or link it rather than assuming
it was read.

Murph also uses the channel name, topic, thread, and connected-account context
to resolve informal company or product names before declaring them unknown. If
one candidate is clear, Murph names that interpretation and answers from the
available account or documentation evidence. If several candidates remain, it
asks which one you meant. Context can help find the right record, but it never
grants access or supplies identity for an account change.

Not every participant in a shared channel has to be an Apostra user. If a
participant's Slack email is not linked to an Apostra account, Murph can
still answer general product and documentation questions using the nearby
channel context. That includes public storefront availability: a participant
can ask for a public brand, storefront, or domain by name, and Murph
can report the matching marketplace-listed storefront's public status,
channels, and regions. Murph does not need an account connection or an exact
domain for that lookup. It cannot read account data, file reports, save
preferences, or make changes for that participant. Account-specific work
requires a linked Apostra user. Murph links unlinked participants to Apostra signup and access-request flow. In a privately connected account
channel, the participant receives a private **Request access from admin**
button without re-entering their email; Murph uses the email supplied by Slack
and asks that account's admins to approve the request. Shared multi-company
channels do not infer an account from the channel, so they continue to use the
email-verified signup flow.

Because a Slack channel can include people from outside your organization,
Murph regularly checks who can read each connected channel. If the members of
a channel span **more than one account** — for example, a channel
shared between a buyer and a publisher they work with — Murph pauses
account-specific answers in that channel and says so, rather than showing one
account's data to another company. General product questions and DMs are
unaffected. An account admin reviews the participants in **Communications**:
they can send an account invitation with an explicit role, keep someone as a
channel guest, identify an external company, or disconnect the channel. Until
that review resolves the unexpected participant, Murph keeps account data and
changes unavailable in the channel.

### Deliberately shared channels

Some channels are shared with another company on purpose — for example, a
channel between a buyer and a publisher they work with. An Apostra admin can
tell Murph in that channel to mark it as **shared** and name each participating
company. Murph resolves the companies, shows their buyer or seller roles, and
records one acting account plus the expected counterparties. For a
buyer–seller channel, the buyer is the acting account and the seller is the
counterparty. If the roles are ambiguous, Murph asks the admin to choose
instead of guessing.

Declaring a buyer–seller channel is also demand evidence: the buyer has a
working relationship in which it wants that seller's supply. Apostra
automatically tracks the seller's marketplace-visible storefront relationship in the buyer's
**Supply I would buy** view. Those relationship-tracked rows stay attached to
the shared-channel declaration and cannot be removed as if they were a manual
request. In a shared channel, Murph:

* **Discusses the relationship freely** — supply you've asked to track for
  that counterparty, whether it's ready, and general product questions.
* **Keeps everything else out of the channel.** Your other sellers,
  campaigns, advertisers, spend, and account settings are never discussed
  there — Murph redirects those questions to a DM or your private channel.
  Supply tracking in the channel works only for the counterparty's own
  domains.
* **Lets you approve specific exceptions.** If a campaign of yours is
  relevant to the shared work, you can tell Murph to share it in the
  channel. Murph asks you to confirm explicitly — "Is it okay to share
  this campaign's details here?" — and only someone from the owning
  company can approve. Once approved, its settings-level details (name,
  status, flight dates, budget) stay discussable in that channel until you
  say "stop sharing it here." Every approval and revocation is recorded.
* **Keeps watching the room.** If someone from a third company appears in
  the channel, Murph pauses account answers again until an admin reviews.

<CardGroup cols={2}>
  <Card title="Storefront onboarding" icon="store" href="/v2/setup/storefront-onboarding">
    The end-to-end flow for standing up a storefront and connecting inventory.
  </Card>

  <Card title="Storefront object guide" icon="cube" href="/v2/object-guides/storefront">
    The storefront resource, business profile, and seller analytics fields.
  </Card>

  <Card title="Sandbox" icon="flask" href="/v2/features/sandbox">
    Test plans and diagnostics for validating your storefront before launch.
  </Card>

  <Card title="Shared Murph rooms" icon="people-group" href="/v2/features/murph-shared-rooms">
    Bring teammates into a Murph conversation with a shareable room link.
  </Card>

  <Card title="Third-party agent diagnostics" icon="stethoscope" href="/v2/storefront/inventory-sources/diagnostics">
    Find source health, recent ADCP Calls, and missing diagnostic gaps.
  </Card>

  <Card title="Murph user preferences" icon="languages" href="/v2/api/murph/user-preferences">
    Set Murph's default language and read display preferences for the current
    user.
  </Card>

  <Card title="Conversation scope" icon="sitemap" href="/v2/api/murph/conversation-scope">
    Set a Murph conversation's account or advertiser scope.
  </Card>

  <Card title="Management UI" icon="browser" href="/v2/ui-guide">
    Navigate the platform dashboard for members, keys, and accounts.
  </Card>
</CardGroup>