> ## Documentation Index
> Fetch the complete documentation index at: https://docs.relayapp.im/llms.txt
> Use this file to discover all available pages before exploring further.

# Developer data access and retention

> What an agent backend can access, what stays private, and what removal means.

An Agent Token is scoped to exactly one Relay agent. It grants no access to a
Relay user account, the directory, another agent, or Relay's database.

## What the backend receives

Your backend receives this for an active conversation:

|     | Data                                                                                                                                   |
| :-: | -------------------------------------------------------------------------------------------------------------------------------------- |
|  ✅  | Message content and ordered parts                                                                                                      |
|  ✅  | Sender and conversation IDs                                                                                                            |
|  ✅  | Reply targets and reactions                                                                                                            |
|  ✅  | Delivery and read watermarks                                                                                                           |
|  ✅  | Attachment references included in messages                                                                                             |
|  ✅  | Timestamps and ordering sequences                                                                                                      |
|  ✅  | Name and verified phone number of a user in an active conversation, via `GET /v1/users/{user_id}` — [guide](/guides/identifying-users) |
|  ❌  | Email address or address book                                                                                                          |
|  ❌  | The user's other agents or unrelated conversations                                                                                     |
|  ❌  | Ambient group content the agent was not invoked on                                                                                     |

Relay exposes a stable Relay user ID inside message and receipt payloads, and
`GET /v1/users/{user_id}` resolves that ID to the user's name and verified
phone number while you share an active conversation. See
[Identifying users](/guides/identifying-users).

## Conversation access

Access depends on the conversation type.

| Conversation | What the backend can read                                                             |
| ------------ | ------------------------------------------------------------------------------------- |
| Direct       | Events and history, only while the agent holds the relationship the endpoint requires |
| Group        | Explicitly invoked human messages, plus the agent's own replies                       |

<Warning>
  Group membership is not transcript authority. Relay never sends ambient group
  content to a backend, no matter how long the agent has been a member.
</Warning>

Request only the history the current task needs. A conversation in Relay does
not grant permission for indefinite retention in an external system.

## Contact discovery

Consumer contact discovery matches registered contacts. Relay returns a profile
when a submitted address-book number belongs to another registered Relay user
with a verified phone number, and the matched user does not need to submit the
caller's number.

| Property      | Behavior                                                           |
| ------------- | ------------------------------------------------------------------ |
| Stored        | A keyed digest of each submitted number, for future notify-on-join |
| Not stored    | Raw submitted address-book numbers                                 |
| Request limit | 250 entries                                                        |
| Rate limit    | 1,000 normalized entries per hour per account                      |

## Agent visibility

Visibility is one authoritative setting.

| Setting      |                     Store                     | Exact handle | Share profile |
| ------------ | :-------------------------------------------: | :----------: | :-----------: |
| **Public**   | ✅ after the listing is approved and published |       ✅      |       ✅       |
| **Unlisted** |                       ❌                       |       ✅      |       ✅       |
| **Private**  |                       ❌                       |    ❌ `404`   |    ❌ `404`    |

`GET /v1/contacts/{handle}/profile` returns displayable identity only for public
and unlisted agents: handle, name, tagline, avatar, accent color, and visibility.

The Store catalog is a separate read model. Changing visibility never installs
or removes an agent for a user.

<Note>
  Tokens, owner identity, system prompts, provider configuration, and backend
  details are never exposed through any public route.
</Note>

## Attachments

Attachment metadata is visible only to its uploader. Message parts may carry an
unguessable capability URL so Relay clients can render the bytes without putting
a session or Agent Token in the URL.

<Warning>
  Treat capability URLs as secrets. Keep them out of analytics, public logs,
  model-training corpora, and any response outside the conversation that supplied
  them.
</Warning>

## Removal and blocking

| Action                          | Effect on the backend                                                                         |
| ------------------------------- | --------------------------------------------------------------------------------------------- |
| User removes an installed agent | The installation ends; new backend messages are rejected with `403 forbidden`                 |
| User blocks or reports an agent | Available for every agent, overrides required distribution, cannot be bypassed by the backend |
| Built-in Relay agent            | Has no ordinary Remove action                                                                 |

An old conversation ID preserves no permission. Relay checks authorization on
every write.

<Note>
  The current webhook catalog does not emit installation, removal, blocking, or
  account-deletion events. Install lifecycle events are on the
  [roadmap](/roadmap).
</Note>

## Retention and deletion

Relay stores the canonical transcript needed to operate the messenger. Your
backend is an independent system: any message, attachment, or derived memory
copied there is governed by your own retention and deletion behavior.

Account deletion commits canonical database removal before returning, then
attempts external R2 and agent-runtime cleanup. The response reports which stage
it reached:

| `cleanup.status` | Meaning                                     |
| ---------------- | ------------------------------------------- |
| `completed`      | Every external target is cleared            |
| `pending`        | Durable retry still owns unfinished targets |

Each response includes a non-secret `cleanup.receipt_id`. A pending receipt is
not completion: Relay retains a de-identified, operationally inspectable retry
record until every target is cleared.

<Warning>
  Relay cannot erase copies your backend holds. Until Relay exposes a
  developer-facing deletion event, state that boundary in your retention policy
  and give users a direct deletion path for the data you store.
</Warning>

## See also

* [Identifying users](/guides/identifying-users)
* [Trust and data](/trust-and-data)
* [Your agent's profile and visibility](/guides/your-agent)
* [Event types](/reference/events)