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

{
  "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:

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

Retrieve it:

curl http://localhost:8080/v1/conversations/conv_abc123 \
  -H "Authorization: Bearer $GOMODEL_MASTER_KEY"

Update its metadata (replaces all metadata):

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:

curl -X DELETE http://localhost:8080/v1/conversations/conv_abc123 \
  -H "Authorization: Bearer $GOMODEL_MASTER_KEY"