OpenAI
6 operations. {prefix} is the route prefix passed to
MapAgentPrism; the template uses /agentprism.
The OpenAPI snapshot cannot express the polymorphic request bodies of the Responses and Chat Completions adapters. Use the [OpenAI-compatible API guide] (/guides/openai-api/) for copyable requests, streaming events, state, and the exact compatibility boundary.
POST {prefix}/v1/chat/completions
Section titled “POST {prefix}/v1/chat/completions”Operation ID: AgentPrismOpenAIChatCompletions
Run endpoint compatible with the OpenAI Chat Completions API.
Stateless: the client carries history. The agent is selected from the ‘model’ field; if not found, ‘metadata.entity_id’ is tried.
Authorization: bearer authentication; Operator role policy when that policy is registered; RunsWrite API-key scope.
| Response | Body | Headers |
|---|---|---|
| 200 OK | application/json → ChatCompletiontext/event-stream → ChatCompletion |
— |
| 400 Bad Request | application/json → OpenAIErrorEnvelope |
— |
| 404 Not Found | application/json → OpenAIErrorEnvelope |
— |
| 502 Bad Gateway | application/json → OpenAIErrorEnvelope |
— |
POST {prefix}/v1/conversations
Section titled “POST {prefix}/v1/conversations”Operation ID: AgentPrismOpenAICreateConversation
Generates a new conversation identifier.
An identifier reservation: the session is born on the first /v1/responses call. The returned identifier is used directly in the ‘conversation’ field.
Authorization: bearer authentication; Operator role policy when that policy is registered; RunsWrite API-key scope.
| Response | Body | Headers |
|---|---|---|
| 200 OK | application/json → ConversationResource |
— |
| 400 Bad Request | application/json → OpenAIErrorEnvelope |
— |
GET {prefix}/v1/conversations/{conversationId}
Section titled “GET {prefix}/v1/conversations/{conversationId}”Operation ID: AgentPrismOpenAIGetConversation
Returns a conversation’s metadata.
A conversation identifier is a reservation, so an id that has never carried a call is still valid and answers 200 with the current time as its creation time. 404 therefore means ‘not yours’, not ‘never used’: an identifier owned by another tenant is reported as missing rather than forbidden, so the API does not confirm that it exists.
Authorization: bearer authentication; Operator role policy when that policy is registered; RunsRead API-key scope.
| Parameter | In | Required | Type | Description and rules |
|---|---|---|---|---|
conversationId |
path | yes | string |
— |
| Response | Body | Headers |
|---|---|---|
| 200 OK | application/json → ConversationResource |
— |
| 404 Not Found | application/json → OpenAIErrorEnvelope |
— |
DELETE {prefix}/v1/conversations/{conversationId}
Section titled “DELETE {prefix}/v1/conversations/{conversationId}”Operation ID: AgentPrismOpenAIDeleteConversation
Deletes a conversation and the session underneath it.
Following the OpenAI shape, the response is 200 with a ‘deleted’ flag rather than 204: the flag is false when the identifier was valid but no session had been created for it yet, so a client can tell a real deletion from a no-op. An identifier owned by another tenant returns 404.
Authorization: bearer authentication; Operator role policy when that policy is registered; RunsWrite API-key scope.
| Parameter | In | Required | Type | Description and rules |
|---|---|---|---|---|
conversationId |
path | yes | string |
— |
| Response | Body | Headers |
|---|---|---|
| 200 OK | application/json → DeletedResource |
— |
| 404 Not Found | application/json → OpenAIErrorEnvelope |
— |
GET {prefix}/v1/conversations/{conversationId}/items
Section titled “GET {prefix}/v1/conversations/{conversationId}/items”Operation ID: AgentPrismOpenAIListConversationItems
Lists a conversation’s messages in the OpenAI item format.
Items come back oldest first, and one stored message can expand into several items — a reply plus its tool calls, for example. ‘?limit=’ trims the list from the end and sets ‘has_more’ to true, which is computed from the real total before trimming, so a truncated list never looks complete. There is no cursor paging: ‘first_id’ and ‘last_id’ describe the returned window only. A conversation with no history returns an empty list, and an identifier owned by another tenant returns 404.
Authorization: bearer authentication; Operator role policy when that policy is registered; RunsRead API-key scope.
| Parameter | In | Required | Type | Description and rules |
|---|---|---|---|---|
conversationId |
path | yes | string |
— |
limit |
query | no | integer (int32) |
pattern `^-?(?:0\ |
| Response | Body | Headers |
|---|---|---|
| 200 OK | application/json → ItemListResource |
— |
| 404 Not Found | application/json → OpenAIErrorEnvelope |
— |
POST {prefix}/v1/responses
Section titled “POST {prefix}/v1/responses”Operation ID: AgentPrismOpenAIResponses
Run endpoint compatible with the OpenAI Responses API.
The agent is selected from the ‘model’ field; if not found, ‘metadata.entity_id’ is tried. If ‘conversation’ is given the session is stored under that identifier; if not, under the generated response identifier, so chaining with ‘previous_response_id’ works.
Authorization: bearer authentication; Operator role policy when that policy is registered; RunsWrite API-key scope.
| Response | Body | Headers |
|---|---|---|
| 200 OK | application/json → JsonElementtext/event-stream → JsonElement |
— |
| 400 Bad Request | application/json → OpenAIErrorEnvelope |
— |
| 404 Not Found | application/json → OpenAIErrorEnvelope |
— |
| 502 Bad Gateway | application/json → OpenAIErrorEnvelope |
— |