---
title: "Materialize an API chat"
method: POST
path: "/chat/{id}/materialize"
tags: ["Chat"]
---

# Materialize an API chat

`POST /chat/{id}/materialize`

## Request

- Base URL: `https://app.gc.ai/api/external/v1`
- URL: `https://app.gc.ai/api/external/v1/chat/{id}/materialize`
- Auth: API key in header `Authorization`
- TypeScript: <https://skmtc.dev/gc-ai/apis/gc-ai-external-api/docs/chat/:id/materialize/post.ts> (a function with typed inputs; its response is checked against the schema)

Surface an API-created chat into chat history and return a shareable deep link.

Chats created through `POST /chat/completions` stay out of chat history (both the GC AI web app and [chat search](https://docs.gc.ai/api-reference/search-chats)) until you materialize them. Use the `chat_id` from a completed completion response. The endpoint is idempotent. Calling it again on an already-materialized chat returns the same link without side effects.

Pass `project_id` to file the chat into a project at the same time, so it is browsable under `GET /projects/{id}/chats`. This requires write access to the project and files a chat that is already materialized.

**Authorization:** User-scoped keys can only materialize chats they created. Organization-scoped keys can only materialize chats created by other organization-scoped keys.

**Who can use the chat afterwards:** An organization-scoped key shares the chat with the whole organization, and every member can continue it in the web app. A user-scoped key keeps the chat owned by that user, so teammates reach it only through the normal sharing rules.

See [Chat Visibility](https://docs.gc.ai/api-reference/concepts/chat-visibility) for how this works.

## Path parameters

- `id` string, uuid, required: The chat ID

## Request body

- MaterializeChatRequest
  - `project_id` string, uuid: File the chat into this project while materializing it. Requires write access to the project. Omit to leave the chat unfiled.

## Response `200`

Chat materialized (or already materialized)

- MaterializeChatResponse
  - `id` string, uuid, required: The chat ID
  - `title` string, nullable, required: The chat title, if generated
  - `chat_url` string, uri, required: Deep link to open the chat in the GC AI web UI
  - `materialized_at` string, date-time, required: When the chat was materialized
  - `project_id` string, uuid, nullable, required: Project the chat is filed under, or null if unfiled

## Other responses

- `400`: Invalid chat ID or request body
- `401`: Missing or malformed API key
- `403`: Token cannot materialize this chat (wrong ownership scope)
- `404`: Chat not found, or target project not found or not writable
- `409`: Chat is not an API-created chat
- `429`: Rate limit exceeded. See [Rate Limits](https://docs.gc.ai/api-reference/concepts/rate-limits) for the tiers, limits, and how to back off.
- `500`: Internal server error
- `503`: Service temporarily unavailable

---

[API](https://skmtc.dev/gc-ai/apis/gc-ai-external-api.md) - [All operations](https://skmtc.dev/gc-ai/apis/gc-ai-external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gc-ai/apis/gc-ai-external-api/revisions/2bbdfddf7107?raw)