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

# Chat Visibility

> Why API chats stay private until you materialize them

Every chat completion you create through the API is saved as a chat, but that chat is **headless** by default. It does not appear in anyone's chat history, not in the GC AI web app and not in the API's own [chat search](/api-reference/search-chats). It exists only as a record you can reach by its `chat_id`. To put it into a person's history, you **materialize** it.

## Why API chats are hidden by default

When you call [`POST /chat/completions`](/api-reference/create-chat-completion), GC AI creates a chat to hold the exchange and returns its `chat_id` in the result envelope. Most API traffic is automated, though: batch contract reviews, a triage bot, a nightly job. If every one of those calls dropped a chat into someone's sidebar, real users' histories would fill up with machine-generated chats they never started.

So API chats start headless. The chat is saved and reachable by `chat_id`, but it stays out of every human-facing listing until a person explicitly **claims** it by materializing it.

## What "hidden" means

An API chat that has not been materialized:

* **Does not appear in the web app.** It never shows up in the chat sidebar or history.
* **Does not appear in API chat search.** [`GET /chat/search`](/api-reference/search-chats) searches the caller's chat history, and the chat is not in it, so search will not return it.
* **Addressable only by `chat_id`.** Visibility is about listings, not access. The chat is still reachable directly by the `chat_id` from the completion response, but you have to hold that id yourself. Capture it (and the answer text) at the time of the call; an unmaterialized chat whose `chat_id` you never kept is effectively lost.

<Note>
  Materialization is not a web-app-only flag. The same gate controls both the web sidebar and API chat search, so an unmaterialized chat is hidden in both. Materializing it makes the chat show up in both at once.
</Note>

## Materializing a chat

Call [`POST /chat/{id}/materialize`](/api-reference/materialize-chat) with the `chat_id` from a completed `POST /chat/completions` response:

```bash theme={null}
curl -X POST https://app.gc.ai/api/external/v1/chat/a1b2c3d4-e5f6-7890-abcd-ef1234567890/materialize \
  -H "Authorization: gcai_your_api_key_here"
```

Materializing a chat does three things:

* **Adds it to chat history**, so it shows up in the GC AI web app and becomes findable through `GET /chat/search`.
* **Returns a shareable deep link** (`chat_url`) that opens the chat in the web app.
* **Is idempotent.** Calling it again on an already-materialized chat returns the same link and changes nothing else.

A common pattern is to run completions fire-and-forget and then materialize only the chats a person actually needs to see, such as the ones a review flagged, rather than every chat the integration creates.

## Who can materialize what

Materialization claims a chat into a person's or an organization's history, so it is scoped to the key that created the chat:

| Key type                    | Can materialize                                       |
| --------------------------- | ----------------------------------------------------- |
| **Personal** (`u:gcai_…`)   | Only chats it created.                                |
| **Organization** (`gcai_…`) | Only chats created by other organization-scoped keys. |

When an organization key materializes a chat that another organization key created, the chat becomes visible to **all members of the organization**, so anyone on the team can open it from the shared link. See [API Keys](/api-reference/concepts/api-keys) for the difference between the two key types.

## Materialization and chat search

[`GET /chat/search`](/api-reference/search-chats) runs hybrid search over the caller's chat history. Two things follow from how visibility works:

* **Search needs a personal key.** Chat history is per-user, so chat search rejects organization keys with `400`. Use a personal key.
* **Search only finds materialized chats.** An API chat is not in anyone's history until it is materialized, so it cannot show up in search before then. If you want an integration's chats to be searchable later, materialize the ones worth keeping.

## Related

* [Create a Chat Completion](/api-reference/create-chat-completion): creates the chat and returns its `chat_id`.
* [Multi-turn Conversations](/api-reference/concepts/multi-turn): continue a chat across turns by passing its `chat_id`.
* [Materialize an API Chat](/api-reference/materialize-chat): surface a chat by `chat_id` and get a deep link.
* [Search Chats](/api-reference/search-chats): hybrid search over a user's chat history.
* [API Keys](/api-reference/concepts/api-keys): personal vs. organization keys and what each can reach.