{
  "components": {
    "responses": {
      "ConversationNotFound": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        },
        "description": "The conversation is absent, expired, deleted, or outside the caller's exact scope."
      },
      "OneForbidden": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        },
        "description": "The credential lacks conversation_history_read scope."
      },
      "OneInvalidRequest": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        },
        "description": "A parameter or request body is invalid."
      },
      "OneRateLimited": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        },
        "description": "The credential rate limit was exceeded.",
        "headers": {
          "Retry-After": {
            "schema": {
              "minimum": 1,
              "type": "integer"
            }
          },
          "x-ratelimit-limit": {
            "schema": {
              "minimum": 0,
              "type": "integer"
            }
          },
          "x-ratelimit-remaining": {
            "schema": {
              "minimum": 0,
              "type": "integer"
            }
          },
          "x-ratelimit-reset": {
            "schema": {
              "minimum": 0,
              "type": "integer"
            }
          }
        }
      },
      "OneUnauthorized": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        },
        "description": "The One API credential is missing, invalid, expired, rotated, revoked, or stale.",
        "headers": {
          "WWW-Authenticate": {
            "schema": {
              "type": "string"
            }
          }
        }
      },
      "OneUnavailable": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        },
        "description": "Authorization or conversation storage is temporarily unavailable."
      }
    },
    "schemas": {
      "ConversationCursor": {
        "description": "Opaque and subject-bound. Clients must not construct or modify it.",
        "maxLength": 4096,
        "minLength": 1,
        "type": "string"
      },
      "ConversationExcerpt": {
        "additionalProperties": false,
        "properties": {
          "lexicalRank": {
            "type": "number"
          },
          "matchKind": {
            "enum": [
              "phrase",
              "lexical",
              "semantic",
              "recent"
            ],
            "type": "string"
          },
          "modality": {
            "$ref": "#/components/schemas/ConversationModality"
          },
          "occurredAt": {
            "format": "date-time",
            "type": "string"
          },
          "role": {
            "enum": [
              "user",
              "assistant"
            ],
            "type": "string"
          },
          "semanticSimilarity": {
            "maximum": 1,
            "minimum": -1,
            "type": "number"
          },
          "sourceReference": {
            "type": "string"
          },
          "text": {
            "maxLength": 512,
            "type": "string"
          },
          "truncated": {
            "type": "boolean"
          }
        },
        "required": [
          "sourceReference",
          "role",
          "text",
          "occurredAt",
          "modality",
          "matchKind",
          "lexicalRank",
          "truncated"
        ],
        "type": "object"
      },
      "ConversationListEnvelope": {
        "additionalProperties": false,
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/ConversationSummary"
            },
            "maxItems": 10,
            "type": "array"
          },
          "hasMore": {
            "type": "boolean"
          },
          "nextCursor": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/ConversationCursor"
              },
              {
                "type": "null"
              }
            ]
          },
          "object": {
            "const": "conversation.list",
            "type": "string"
          }
        },
        "required": [
          "object",
          "data",
          "hasMore",
          "nextCursor"
        ],
        "type": "object"
      },
      "ConversationMessage": {
        "additionalProperties": false,
        "properties": {
          "modality": {
            "$ref": "#/components/schemas/ConversationModality"
          },
          "occurredAt": {
            "format": "date-time",
            "type": "string"
          },
          "role": {
            "enum": [
              "user",
              "assistant"
            ],
            "type": "string"
          },
          "sourceReference": {
            "type": "string"
          },
          "text": {
            "maxLength": 4096,
            "type": "string"
          },
          "truncated": {
            "type": "boolean"
          }
        },
        "required": [
          "sourceReference",
          "role",
          "text",
          "occurredAt",
          "modality",
          "truncated"
        ],
        "type": "object"
      },
      "ConversationMessageListEnvelope": {
        "additionalProperties": false,
        "properties": {
          "conversationId": {
            "pattern": "^conversation_[a-z0-9_-]+$",
            "type": "string"
          },
          "data": {
            "items": {
              "$ref": "#/components/schemas/ConversationMessage"
            },
            "maxItems": 50,
            "type": "array"
          },
          "hasMore": {
            "type": "boolean"
          },
          "lifecycle": {
            "enum": [
              "active",
              "archived"
            ],
            "type": "string"
          },
          "nextCursor": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/ConversationCursor"
              },
              {
                "type": "null"
              }
            ]
          },
          "object": {
            "const": "conversation.message.list",
            "type": "string"
          },
          "retentionState": {
            "const": "retained",
            "type": "string"
          }
        },
        "required": [
          "object",
          "conversationId",
          "lifecycle",
          "retentionState",
          "data",
          "hasMore",
          "nextCursor"
        ],
        "type": "object"
      },
      "ConversationModality": {
        "enum": [
          "typed",
          "voice"
        ],
        "type": "string"
      },
      "ConversationSummary": {
        "additionalProperties": false,
        "properties": {
          "conversationId": {
            "pattern": "^conversation_[a-z0-9_-]+$",
            "type": "string"
          },
          "excerpts": {
            "items": {
              "$ref": "#/components/schemas/ConversationExcerpt"
            },
            "maxItems": 3,
            "type": "array"
          },
          "lastActivityAt": {
            "format": "date-time",
            "type": "string"
          },
          "modalities": {
            "items": {
              "$ref": "#/components/schemas/ConversationModality"
            },
            "maxItems": 2,
            "type": "array",
            "uniqueItems": true
          },
          "title": {
            "type": "string"
          }
        },
        "required": [
          "conversationId",
          "title",
          "lastActivityAt",
          "modalities",
          "excerpts"
        ],
        "type": "object"
      },
      "ErrorEnvelope": {
        "properties": {
          "error": {
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "param": {
                "oneOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "type": {
                "type": "string"
              }
            },
            "required": [
              "type",
              "code",
              "message",
              "param"
            ],
            "type": "object"
          }
        },
        "required": [
          "error"
        ],
        "type": "object"
      },
      "McpJsonRpcRequest": {
        "description": "One JSON-RPC 2.0 request. A request without an id is a notification.",
        "properties": {
          "id": {
            "description": "The request identifier. A string or a number."
          },
          "jsonrpc": {
            "const": "2.0",
            "type": "string"
          },
          "method": {
            "enum": [
              "initialize",
              "notifications/initialized",
              "tools/list",
              "tools/call"
            ],
            "type": "string"
          },
          "params": {
            "additionalProperties": true,
            "type": "object"
          }
        },
        "required": [
          "jsonrpc",
          "method"
        ],
        "type": "object"
      },
      "McpJsonRpcResponse": {
        "description": "One JSON-RPC 2.0 response with a result member or an error member.",
        "properties": {
          "error": {
            "properties": {
              "code": {
                "type": "integer"
              },
              "message": {
                "type": "string"
              }
            },
            "type": "object"
          },
          "id": {
            "description": "The request identifier or null."
          },
          "jsonrpc": {
            "const": "2.0",
            "type": "string"
          },
          "result": {
            "additionalProperties": true,
            "type": "object"
          }
        },
        "required": [
          "jsonrpc",
          "id"
        ],
        "type": "object"
      },
      "OmegaCompactResponseBody": {
        "allOf": [
          {
            "$ref": "https://raw.githubusercontent.com/openresponses/openresponses/92c12d96d7b61d6d15e2214daa5e9c6000ab6e1c/public/openapi/2026-04-24/openapi.json#/components/schemas/CompactResponseMethodPublicBody"
          },
          {
            "properties": {
              "model": {
                "const": "omega-agent",
                "type": "string"
              }
            },
            "required": [
              "model"
            ],
            "type": "object"
          }
        ]
      },
      "OmegaCreateResponseBody": {
        "allOf": [
          {
            "$ref": "https://raw.githubusercontent.com/openresponses/openresponses/92c12d96d7b61d6d15e2214daa5e9c6000ab6e1c/public/openapi/2026-04-24/openapi.json#/components/schemas/CreateResponseBody"
          },
          {
            "properties": {
              "background": {
                "const": false,
                "description": "Stored background responses are outside the One profile. Disconnect the active transport to cancel work.",
                "type": "boolean"
              },
              "model": {
                "oneOf": [
                  {
                    "const": "omega-agent",
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "tools": {
                "description": "Developer-hosted function tools validated as a bounded One catalog projection. Function names are unique lowercase ASCII identifiers.",
                "maxItems": 128,
                "type": [
                  "array",
                  "null"
                ]
              }
            },
            "type": "object"
          }
        ],
        "unevaluatedProperties": false,
        "x-one-limits": {
          "modelToolResultBytes": 65536,
          "requestBytes": 524288,
          "responseBytes": 2097152,
          "streamEvents": 8192,
          "streamFrameBytes": 524288,
          "toolSchemaBytes": 65536,
          "tools": 128
        }
      },
      "SarahCreateResponseBody": {
        "$ref": "#/components/schemas/OmegaCreateResponseBody"
      },
      "SignedDecimalString": {
        "pattern": "^-?(0|[1-9][0-9]*)(\\.[0-9]+)?$",
        "type": "string"
      },
      "UnsignedDecimalString": {
        "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]+)?$",
        "type": "string"
      }
    },
    "securitySchemes": {
      "mcpBearer": {
        "bearerFormat": "OpenAuth or one_mcp_v1 credential",
        "description": "A verified OpenAuth access token, revisioned digest-only One MCP credential, or delegated One voice grant bound to this resource.",
        "scheme": "bearer",
        "type": "http"
      },
      "nostrHttpAuth": {
        "description": "A base64 NIP-98 event that signs the URL, method, and payload hash.",
        "scheme": "Nostr",
        "type": "http"
      },
      "oneApiCredential": {
        "bearerFormat": "one_mcp_v1",
        "description": "A live, revisioned, digest-stored One API credential bound to one principal, tenant, and workspace. Conversation history also requires mcp and conversation_history_read scopes.",
        "scheme": "bearer",
        "type": "http"
      },
      "openAgentsAccessToken": {
        "bearerFormat": "OpenAuth access token",
        "scheme": "bearer",
        "type": "http"
      }
    }
  },
  "info": {
    "description": "This document defines the One profile of Open Responses 2026-04-24. The compatibility logical model is omega-agent.",
    "title": "OpenAgents One Responses API",
    "version": "2026-04-24"
  },
  "openapi": "3.1.0",
  "paths": {
    "/.well-known/oauth-protected-resource": {
      "get": {
        "operationId": "getMcpProtectedResourceMetadata",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            },
            "description": "OAuth protected-resource metadata for the One MCP gateway."
          }
        },
        "summary": "Discover the One MCP OAuth protected resource"
      }
    },
    "/api/mcp": {
      "$ref": "#/paths/~1mcp"
    },
    "/mcp": {
      "post": {
        "description": "This route serves the MCP Streamable HTTP JSON-RPC subset: initialize, notifications/initialized, tools/list, and tools/call. The route accepts a verified OpenAuth access token, a revisioned One API credential, or a delegated One voice grant. Cataloged tools run through the One policy boundary and unknown tools fail closed.",
        "operationId": "callMcpGateway",
        "parameters": [
          {
            "description": "The MCP session identifier. The gateway is stateless and accepts every value.",
            "in": "header",
            "name": "mcp-session-id",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/McpJsonRpcRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/McpJsonRpcResponse"
                }
              }
            },
            "description": "The JSON-RPC response. The mcp-session-id response header carries the session identifier."
          },
          "202": {
            "description": "The gateway accepted a JSON-RPC notification."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/McpJsonRpcResponse"
                }
              }
            },
            "description": "The voice grant bearer token is missing or not valid."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/McpJsonRpcResponse"
                }
              }
            },
            "description": "The MCP gateway is not configured."
          }
        },
        "security": [
          {
            "mcpBearer": []
          }
        ],
        "summary": "Call the MCP tool gateway"
      }
    },
    "/responses": {
      "post": {
        "operationId": "createOmegaResponse",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OmegaCreateResponseBody"
              }
            },
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/OmegaCreateResponseBody"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "https://raw.githubusercontent.com/openresponses/openresponses/92c12d96d7b61d6d15e2214daa5e9c6000ab6e1c/public/openapi/2026-04-24/openapi.json#/components/schemas/ResponseResource"
                }
              },
              "text/event-stream": {
                "schema": {
                  "$ref": "https://raw.githubusercontent.com/openresponses/openresponses/92c12d96d7b61d6d15e2214daa5e9c6000ab6e1c/public/openapi/2026-04-24/openapi.json#/paths/~1responses/post/responses/200/content/text~1event-stream/schema"
                }
              }
            },
            "description": "The response is complete or is an event stream."
          },
          "default": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "The request failed."
          }
        },
        "summary": "Create a One response"
      },
      "x-openresponses-websocket": {
        "clientMessage": {
          "$ref": "https://raw.githubusercontent.com/openresponses/openresponses/92c12d96d7b61d6d15e2214daa5e9c6000ab6e1c/public/openapi/2026-04-24/openapi.json#/components/schemas/WebSocketResponseCreateEvent"
        },
        "description": "Open a WebSocket connection. Send one response.create event at a time. Closing the client socket cancels active provider work and discards queued turns.",
        "errorMessage": {
          "$ref": "https://raw.githubusercontent.com/openresponses/openresponses/92c12d96d7b61d6d15e2214daa5e9c6000ab6e1c/public/openapi/2026-04-24/openapi.json#/components/schemas/WebSocketErrorEvent"
        }
      }
    },
    "/responses/compact": {
      "post": {
        "operationId": "compactOmegaResponse",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OmegaCompactResponseBody"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "https://raw.githubusercontent.com/openresponses/openresponses/92c12d96d7b61d6d15e2214daa5e9c6000ab6e1c/public/openapi/2026-04-24/openapi.json#/components/schemas/CompactResource"
                }
              }
            },
            "description": "The compacted response."
          },
          "default": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "The request failed."
          }
        },
        "summary": "Compact an Omega Agent conversation"
      }
    },
    "/v1/conversations": {
      "get": {
        "description": "Returns retained Sarah conversations for the exact credential principal, tenant, and workspace. Lexical search is available before semantic embeddings are ready.",
        "operationId": "listSarahConversations",
        "parameters": [
          {
            "description": "Optional lexical query, bounded to 512 UTF-8 bytes.",
            "in": "query",
            "name": "query",
            "required": false,
            "schema": {
              "maxLength": 512,
              "type": "string"
            }
          },
          {
            "description": "Opaque nextCursor returned by the previous page.",
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/ConversationCursor"
            }
          },
          {
            "description": "Number of conversations to return.",
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 10,
              "maximum": 10,
              "minimum": 1,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConversationListEnvelope"
                }
              }
            },
            "description": "A bounded page of self-scoped conversations."
          },
          "400": {
            "$ref": "#/components/responses/OneInvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/OneUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/OneForbidden"
          },
          "429": {
            "$ref": "#/components/responses/OneRateLimited"
          },
          "503": {
            "$ref": "#/components/responses/OneUnavailable"
          }
        },
        "security": [
          {
            "oneApiCredential": []
          }
        ],
        "summary": "List or search the caller's conversations"
      },
      "servers": [
        {
          "url": "https://api.openagents.com"
        }
      ]
    },
    "/v1/conversations/{conversation_id}/messages": {
      "get": {
        "description": "Returns bounded chronological user and assistant messages. Missing and out-of-scope identifiers share the same non-revealing 404.",
        "operationId": "listSarahConversationMessages",
        "parameters": [
          {
            "in": "path",
            "name": "conversation_id",
            "required": true,
            "schema": {
              "pattern": "^conversation_[a-z0-9_-]+$",
              "type": "string"
            }
          },
          {
            "description": "Opaque nextCursor returned by the previous page.",
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/ConversationCursor"
            }
          },
          {
            "description": "Number of messages to return.",
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 50,
              "maximum": 50,
              "minimum": 1,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConversationMessageListEnvelope"
                }
              }
            },
            "description": "A bounded chronological message page."
          },
          "400": {
            "$ref": "#/components/responses/OneInvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/OneUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/OneForbidden"
          },
          "404": {
            "$ref": "#/components/responses/ConversationNotFound"
          },
          "429": {
            "$ref": "#/components/responses/OneRateLimited"
          },
          "503": {
            "$ref": "#/components/responses/OneUnavailable"
          }
        },
        "security": [
          {
            "oneApiCredential": []
          }
        ],
        "summary": "Page through one of the caller's conversations"
      },
      "servers": [
        {
          "url": "https://api.openagents.com"
        }
      ]
    },
    "/v1/sarah/responses": {
      "post": {
        "description": "Creates one durable, self-scoped Sarah conversation using a revocable workspace-bound One API credential.",
        "operationId": "createSarahResponse",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SarahCreateResponseBody"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "https://raw.githubusercontent.com/openresponses/openresponses/92c12d96d7b61d6d15e2214daa5e9c6000ab6e1c/public/openapi/2026-04-24/openapi.json#/components/schemas/ResponseResource"
                }
              },
              "text/event-stream": {
                "schema": {
                  "$ref": "https://raw.githubusercontent.com/openresponses/openresponses/92c12d96d7b61d6d15e2214daa5e9c6000ab6e1c/public/openapi/2026-04-24/openapi.json#/paths/~1responses/post/responses/200/content/text~1event-stream/schema"
                }
              }
            },
            "description": "The response is complete or is an event stream."
          },
          "400": {
            "$ref": "#/components/responses/OneInvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/OneUnauthorized"
          },
          "429": {
            "$ref": "#/components/responses/OneRateLimited"
          },
          "503": {
            "$ref": "#/components/responses/OneUnavailable"
          }
        },
        "security": [
          {
            "oneApiCredential": []
          }
        ],
        "summary": "Create a response with Sarah"
      },
      "servers": [
        {
          "url": "https://api.openagents.com"
        }
      ]
    }
  },
  "security": [
    {
      "nostrHttpAuth": []
    },
    {
      "openAgentsAccessToken": []
    }
  ],
  "servers": [
    {
      "url": "https://api.openagents.com/v1"
    }
  ]
}