Skip to main content
Every Apostra conversation has a scope: either your account or a single advertiser. The scope is set when the conversation is created and never changes, so a conversation’s context stays stable across turns. Account-scoped conversations are the place for cross-advertiser work; advertiser-scoped conversations keep Apostra focused on one advertiser. In Apostra web UI, selecting an advertiser and opening Apostra from that advertiser context starts an advertiser-scoped conversation automatically. Opening Apostra from the organization context starts an account-scoped conversation. This UI selection does not change direct Buyer API or MCP campaign calls: those calls continue to use the advertiser or account scope in their own request and authentication context.
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 literal search term to the conversation-list endpoint to find a prior Apostra room by title, participant, or user/assistant transcript text:
curl
Search returns only the authenticated member’s own rooms and rooms that a teammate explicitly shared within the same account. Private teammate rooms, other accounts, archived rooms, tool output, and system context are excluded. The term is treated literally, may contain up to 200 characters, and does not change the endpoint’s existing pagination or authorization rules. In the Apostra rail, All opens the portable Conversation history Page rather than expanding the rail. The Page is limited to the account or advertiser you are currently working in; changing advertiser requires opening history again from that advertiser’s scope.

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 own crm 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 the customer_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 public scopeType 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 — scopeType is not customer or advertiser, or scopeId exceeds 120 characters.
  • 401 UNAUTHORIZED — missing or invalid bearer token.
  • 403 FORBIDDEN — Apostra is not enabled for the caller’s account.
See Errors for the full error contract.

Ask Apostra

How Apostra works as the in-product assistant.

Apostra user preferences

Set Apostra’s default language and read display preferences.