These endpoints are available only when Apostra is enabled for the caller’s
account.
Set a conversation scope
POST /api/v2/murph/chat
The first message of a conversation accepts an optional scope. Omit it —
or send scopeType: "customer" — for an account-scoped conversation. Send
scopeType: "advertiser" with the advertiser’s id in scopeId to scope the
conversation to one advertiser.
curl
Request fields
The scope is honored only on the first message of a conversation — it is
set once at creation and is immutable. Sending
scopeType/scopeId on a
later turn of an existing conversation has no effect; the stored scope always
wins. To work in a different scope, start a new conversation.
Read the scope
GET /api/v2/murph/conversations
Every conversation summary carries its scope, so you can group or filter
conversations by the account or advertiser they belong to. The
single-conversation endpoint, GET /api/v2/murph/conversations/{conversationUid},
returns the same fields.
Response (excerpt)
Search conversation history
Add a literalsearch term to the conversation-list endpoint to find a prior
Apostra room by title, participant, or user/assistant transcript text:
curl
What an advertiser-scoped conversation acts on
An advertiser-scoped conversation answers for its advertiser. When Apostra reads or writes something that belongs to an advertiser and the request does not say which one — “how are my campaigns doing”, “show me my creatives” — it uses the conversation’s advertiser. When a request names a different advertiser, Apostra declines it and tells you to start a conversation for that advertiser; it never quietly answers for the other one, and it never quietly changes the request to your own advertiser either. To work on another advertiser, start a new conversation scoped to it. This is how every advertiser-scoped conversation behaves, whichever Apostra features your account is enrolled in. Naming an object by its own id works the same way. When a request points at a campaign, media buy, proposal, RFP, audience, creative, creative asset, creative collection, creative session, catalog, event source, property list or directed-campaign subscription that belongs to another advertiser in your account, Apostra declines it and tells you to start a conversation for that advertiser. An id your account does not hold is declined as not found, without saying whether it exists anywhere else. An object your account holds that is attached to no advertiser at all is declined too, with a note that it needs an advertiser first — that is a record to repair rather than an account-level object. An object scoped to a campaign belongs to that campaign’s advertiser. Most creative collections and creative sessions are scoped that way rather than to an advertiser directly, and they work normally in a conversation for the advertiser whose campaign they sit under. Every object belongs to one advertiser, except a property list, which several advertisers can share — a conversation for any of them can work on it. If some other object turns out to be attached to more than one advertiser, Apostra declines it and says the record needs fixing, rather than guessing which advertiser you meant. Naming an object you are about to create is not the same thing. Where you choose the id yourself — an audience, an event source or a catalog — that id belongs to one advertiser, not to the whole account: each advertiser can hold its owncrm audience, and they are different objects. A save in this conversation
always reads and writes its advertiser’s, creating it on the first save, and
never reaches another advertiser’s object of the same name.
Web approvals are not readable in an advertiser-scoped conversation. An
approval is recorded for the whole account and does not say which advertiser it
is about, so a conversation for one advertiser cannot tell its own approvals
from another’s. Apostra declines to list or open them there and points you to
the approval link the request returned, or to an account-scoped conversation,
which reads every approval waiting on the account.
Past conversations are not readable in an advertiser-scoped conversation
either. Your history can hold conversations for other advertisers and for the
whole account, so a conversation for one advertiser cannot tell which of them
are about its own advertiser. Apostra declines to search or open them there and
suggests an account-scoped conversation, which reads your own conversations and
the ones teammates shared. The conversation you are in already carries its own
history, and the conversation history Page in the Apostra rail still lists only
the account or advertiser you are working in.
One tool is unavailable in an advertiser-scoped conversation: the generic
buyer-API call, which runs any named v2 buyer operation with a free-form body
that cannot be held to one advertiser. Apostra declines it and uses the
ordinary tools instead, which are bound. An account-scoped conversation is
unaffected.
A few things belong to the account rather than to one advertiser, and work the
same way in either kind of conversation: your plan and billing, notification
settings, your list of advertisers, your retained work records (sessions), and
support requests. A conversation for one advertiser cannot open another
advertiser’s chat as a retained work record: those records answer a buyer
account only for the seller exchanges it took part in, and those name no
advertiser.
An account-scoped conversation is unchanged — it works across every advertiser
in the account.
Scope and access
Scope is focus, not permission. Every Apostra conversation is isolated by thecustomer_id of the authenticated caller, and that account remains the access
boundary regardless of the conversation’s scope — choosing an advertiser
narrows what the conversation acts on inside your account, not what your
account can reach. Direct Buyer API and MCP calls are unaffected: they carry
their own advertiser or account scope.
Internal TARS project and initiative scope
Authenticated TARS PM-seat surfaces can also bind a conversation to one Linear project or initiative. This internal scope is selected by the trusted host and is not supplied through the publicscopeType or scopeId fields above. TARS
uses it to read the canonical investment recommendation and to ensure a staged
PM investment decision can be confirmed only for the same accountable human,
project or initiative, and proposal targets that were originally displayed.
The scope is preserved with a pending confirmation so an approved replay cannot
drift to a newly selected project or initiative. Admin, ordinary TARS chat, and
Slack therefore produce the same durable decision semantics even though the
server records their provenance separately. This binding narrows the PM
conversation context; it grants no Build Room nomination, admission, launch, or
funding authority.
Errors
400 VALIDATION_ERROR—scopeTypeis notcustomeroradvertiser, orscopeIdexceeds 120 characters.401 UNAUTHORIZED— missing or invalid bearer token.403 FORBIDDEN— Apostra is not enabled for the caller’s account.
Related
Ask Apostra
How Apostra works as the in-product assistant.
Apostra user preferences
Set Apostra’s default language and read display preferences.