Conversations

A conversation stores the items of a multi-turn exchange on the server. Pass its ID as conversation to responses.create(). The conversation's items are prepended to your input, and the new input and output are appended to it. You don't need to replay history or chain response IDs.

The endpoints are OpenAI-compatible, under https://api.glexir.com/v1/conversations.

Quick start

import Glexir from "@glexir/sdk";

const glexir = new Glexir({ apiKey: process.env.GLEXIR_API_KEY });

const conversation = await glexir.conversations.create({ metadata: { topic: "support" } });

const first = await glexir.responses.create({
  model: "gpt-5.4-mini",
  conversation: conversation.id,
  input: "My name is Ada.",
});

const second = await glexir.responses.create({
  model: "gpt-5.4-mini",
  conversation: conversation.id,
  input: "What is my name?",
});

console.log(first.output_text);
console.log(second.output_text);

Operations

Every method takes request options as its last argument. Conversations are not billed by themselves; you pay for the responses that use them.

A conversation belongs to the Glexir organization that created it. Using another conversation ID with any of these endpoints, or with responses.create(), returns 404 (No conversation found with id '...').

The Conversation object

Create a conversation

conversations.create(body?, options?). Both fields are optional.

import Glexir from "@glexir/sdk";

const glexir = new Glexir();

const conversation = await glexir.conversations.create({
  metadata: { customer: "acme" },
  items: [
    { role: "developer", content: "You are a support agent for Acme." },
    { role: "user", content: "Hi, I need help with my order." },
  ],
});

console.log(conversation.id);

The gateway forwards only items and metadata; other fields are dropped. Items go through the same checks as Responses input: audio parts and items from OpenAI-hosted tools return 400 unsupported_on_glexir, and file_id references must be files you uploaded through Glexir. See Input the gateway rejects.

Retrieve a conversation

import Glexir from "@glexir/sdk";

const glexir = new Glexir();

const conversation = await glexir.conversations.retrieve("conv_123");
console.log(conversation.metadata);

Update a conversation

conversations.update(conversationId, body, options?) replaces the metadata. Metadata is the only field you can change.

import Glexir from "@glexir/sdk";

const glexir = new Glexir();

const conversation = await glexir.conversations.update("conv_123", { metadata: { status: "resolved" } });
console.log(conversation.metadata);

ConversationUpdateParams is { metadata: Record<string, string> | null }. metadata is required; without it the gateway returns 400 ("metadata is required.").

Delete a conversation

import Glexir from "@glexir/sdk";

const glexir = new Glexir();

const deleted = await glexir.conversations.delete("conv_123");
console.log(deleted.deleted);

Returns ConversationDeleted: { id, deleted, object: "conversation.deleted" }. Deleting a conversation does not delete its items. After deletion the ID returns 404 on Glexir.

Add items

conversations.items.create(conversationId, params, options?) appends up to 20 items.

import Glexir from "@glexir/sdk";

const glexir = new Glexir();

const added = await glexir.conversations.items.create("conv_123", {
  items: [{ role: "user", content: "Also, can I change the delivery address?" }],
});

console.log(added.data.map((item) => item.id));

Returns ConversationItemList: { object: "list", data, first_id, last_id, has_more }. The same input checks as create() apply.

List items

conversations.items.list(conversationId, query?, options?) returns a PagePromise<ConversationItem>. Iterate it with for await to walk every page, or await it for one page. Items are newest first unless you pass order: "asc". See Pagination.

import Glexir from "@glexir/sdk";

const glexir = new Glexir();

for await (const item of glexir.conversations.items.list("conv_123", { order: "asc" })) {
  if (item.type === "message") console.log(item.role, item.content);
}

ConversationItem is the same type as ResponseItem: messages, reasoning items, function and custom tool calls with their outputs, and compaction items. Conversation messages may also use a plain text content part.

Retrieve an item

import Glexir from "@glexir/sdk";

const glexir = new Glexir();

const item = await glexir.conversations.items.retrieve("conv_123", "msg_456");
console.log(item.type);

conversations.items.retrieve(conversationId, itemId, query?, options?). ItemRetrieveParams is { include?: ResponseIncludable[] }.

Delete an item

import Glexir from "@glexir/sdk";

const glexir = new Glexir();

const conversation = await glexir.conversations.items.delete("conv_123", "msg_456");
console.log(conversation.id);

conversations.items.delete(conversationId, itemId, options?) removes the item and returns the updated Conversation.

Using a conversation with Responses

• Pass conversation: "conv_123" or conversation: { id: "conv_123" } to responses.create().
• Do not combine conversation with previous_response_id.
• Before running a request with a conversation, Glexir reserves credit for about 50,000 tokens of earlier context, because it does not track the conversation's size. The reservation is released and you pay only for actual usage. If your balance is low, this reservation can cause a 402.
• Every file and response referenced in the request must live on the same upstream account as the conversation. Otherwise the request fails with 409 cross_account_reference.

Errors

See HTTP error codes for errors every endpoint can return.