> ## Documentation Index
> Fetch the complete documentation index at: https://gomodel-docs-benchmark-writeup-and-tooling.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Conversations API

> Create, retrieve, update, and delete OpenAI-compatible conversations through GoModel.

## Overview

GoModel exposes OpenAI-compatible Conversations API endpoints under
`/v1/conversations`.

Conversations are a **gateway-managed resource**. The OpenAI Conversations API
is provider-specific, so GoModel generates the conversation ID and stores the
conversation itself. This keeps `/v1/conversations` available and consistent
regardless of which provider routes your model traffic, and requires no
provider configuration.

## Supported endpoints

| Endpoint                        | Behavior                                                         |
| ------------------------------- | ---------------------------------------------------------------- |
| `POST /v1/conversations`        | Creates a conversation. Accepts optional `items` and `metadata`. |
| `GET /v1/conversations/{id}`    | Returns a stored conversation.                                   |
| `POST /v1/conversations/{id}`   | Replaces the conversation `metadata` in full.                    |
| `DELETE /v1/conversations/{id}` | Deletes a stored conversation.                                   |

## Conversation object

```json theme={null}
{
  "id": "conv_a1b2c3d4e5f6...",
  "object": "conversation",
  "created_at": 1741900000,
  "metadata": {}
}
```

`metadata` is always present and serializes as `{}` when empty.

## Limits

GoModel enforces the OpenAI Conversations limits so the public contract stays
compatible:

* `items` — at most 20 entries on create.
* `metadata` — at most 16 key-value pairs; keys up to 64 characters; values up
  to 512 characters.

The `items` array is accepted and stored with the conversation. It is not yet
exposed through a conversation items listing endpoint.

## Storage and retention

Conversations are held in an in-memory store. They survive across requests but
not process restarts. Retention is bounded: conversations expire after 30 days
and the store keeps at most 10,000 conversations, evicting the oldest first.

## Errors

GoModel returns OpenAI-compatible errors:

* `400 invalid_request_error` — invalid body, missing `metadata` on update, or a
  limit exceeded (the `param` field names the offending field).
* `404 not_found_error` — the conversation ID does not exist.

## Examples

Create a conversation:

```bash theme={null}
curl http://localhost:8080/v1/conversations \
  -H "Authorization: Bearer $GOMODEL_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": { "topic": "support" }
  }'
```

Retrieve it:

```bash theme={null}
curl http://localhost:8080/v1/conversations/conv_abc123 \
  -H "Authorization: Bearer $GOMODEL_MASTER_KEY"
```

Update its metadata (replaces all metadata):

```bash theme={null}
curl http://localhost:8080/v1/conversations/conv_abc123 \
  -H "Authorization: Bearer $GOMODEL_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": { "topic": "billing" }
  }'
```

Delete it:

```bash theme={null}
curl -X DELETE http://localhost:8080/v1/conversations/conv_abc123 \
  -H "Authorization: Bearer $GOMODEL_MASTER_KEY"
```