> ## 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.
# Conversation scope
> Set a Murph conversation's account or advertiser scope
Every Murph 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 Murph focused on one advertiser.
In Apostra web UI, selecting an advertiser and opening Murph from that
advertiser context starts an advertiser-scoped conversation automatically.
Opening Murph 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 Murph 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.
```bash curl theme={null}
curl -X POST https://api.apostra.com/api/v2/murph/chat \
-H "Authorization: Bearer $SCOPE3_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "How are my campaigns pacing?",
"scopeType": "advertiser",
"scopeId": "522"
}'
```
### Request fields
| Field | Type | Required | Notes |
| ----------- | ------------------------------ | -------- | ------------------------------------------------------------------------------------------------------ |
| `scopeType` | `"customer"` \| `"advertiser"` | No | Scope for the new conversation. Defaults to `customer` when omitted. |
| `scopeId` | string | No | The advertiser id when `scopeType` is `advertiser`. Max 120 characters. Not used for `customer` scope. |
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)
```json theme={null}
{
"conversations": [
{
"conversationUid": "9b1c…",
"scopeType": "advertiser",
"scopeId": "522"
},
{
"conversationUid": "3f0a…",
"scopeType": "customer",
"scopeId": null
}
]
}
```
| Field | Type | Notes |
| ----------- | ------------------------------ | ----------------------------------------------------------------------------- |
| `scopeType` | `"customer"` \| `"advertiser"` | The conversation scope. Always present. |
| `scopeId` | string \| null | The advertiser id when `scopeType` is `advertiser`; `null` for account scope. |
## Search conversation history
Add a literal `search` term to the conversation-list endpoint to find a prior
Murph room by title, participant, or user/assistant transcript text:
```bash curl theme={null}
curl "https://api.apostra.com/api/v2/murph/conversations?search=campaign&take=20" \
-H "Authorization: Bearer $SCOPE3_API_KEY"
```
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 Murph 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.
## Scope and access
Conversation scope is **contextual**: it organizes your conversations and frames
Murph's responses around the chosen node. It does not change what a conversation
can access. Every Murph 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 the conversation's
focus, not its permissions.
## 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` — Murph is not enabled for the caller's account.
See [Errors](/v2/reference/errors) for the full error contract.
## Related
How Murph works as the in-product assistant.
Set Murph's default language and read display preferences.