A stateful, OpenAI-compatible Responses API for building agentic applications on PhariaAI. Supports conversations, response persistence and retrieval, guardrail checks, client-executed function tools and server-executed MCP (Model Context Protocol) tools that the service invokes in an agentic loop on the caller's behalf.
{
"openapi": "3.1.0",
"info": {
"title": "Stateful Responses",
"version": "0.4.23"
},
"paths": {
"/health": {
"get": {
"tags": [
"Operations"
],
"summary": "Health Check",
"description": "Health check endpoint with optional broker connectivity check.",
"operationId": "health_check_health_get",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
}
}
}
},
"/": {
"get": {
"tags": [
"Operations"
],
"summary": "Root",
"description": "Root endpoint.",
"operationId": "root__get",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"additionalProperties": {
"type": "string"
},
"type": "object",
"title": "Response Root Get"
}
}
}
}
}
}
},
"/models": {
"get": {
"tags": [
"Models"
],
"summary": "Get Models Endpoint",
"description": "Proxy GET /models to the configured models-available URL.",
"operationId": "get_models_endpoint_models_get",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
}
},
"security": [
{
"HTTPBearer": []
}
]
}
},
"/v1/responses": {
"post": {
"tags": [
"Responses"
],
"summary": "Post Responses Endpoint",
"description": "Handle POST /v1/responses - with history reconstruction and storage.\n\nIf previous_response_id is provided, reconstructs the conversation history\nand includes it in the request to the backend. Stores the request-response\npair for future history reconstruction.\n\nInstructions resolution priority:\n1. prompt.id (render template with variables)\n2. explicit instructions field\n3. inherited from previous_response_id\n4. default_system_prompt from config\n\nSupports both streaming (stream=true) and non-streaming modes.\nSupports background mode (background=true) returning 202.",
"operationId": "post_responses_endpoint_v1_responses_post",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResponseRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "When `stream=false` (default), returns a JSON response. When `stream=true`, returns Server-Sent Events.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResponseResponse"
}
},
"text/event-stream": {
"schema": {
"type": "string",
"description": "Server-Sent Events stream following the OpenAI Responses API format.\n\nEach event is sent as `data: {json}\\n\\n` with the following event types:\n\n- `response.created` \u2014 initial response object (status: in_progress)\n- `response.in_progress` \u2014 status update\n- `response.output_item.added` \u2014 new output item added\n- `response.content_part.added` \u2014 new content part added\n- `response.output_text.delta` \u2014 incremental text delta\n- `response.completed` \u2014 final event with complete response object\n\nThe stream ends with `data: [DONE]\\n\\n`."
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically."
},
"425": {
"description": "Too Early",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"501": {
"description": "Not Implemented",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"502": {
"description": "Bad Gateway",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"HTTPBearer": []
}
]
}
},
"/v1/responses/{response_id}": {
"get": {
"tags": [
"Responses"
],
"summary": "Get Responses Endpoint",
"description": "Handle GET /v1/responses/{response_id} - retrieve stored response.\n\nSupports both streaming and non-streaming retrieval.\nFor req_* IDs (background requests), checks pending status first.",
"operationId": "get_responses_endpoint_v1_responses__response_id__get",
"security": [
{
"HTTPBearer": []
}
],
"parameters": [
{
"name": "response_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Response Id"
}
},
{
"name": "stream",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"default": false,
"title": "Stream"
}
},
{
"name": "include_deleted",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"description": "Include soft-deleted responses. Admin-only; returns 403 for non-admin callers.",
"default": false,
"title": "Include Deleted"
},
"description": "Include soft-deleted responses. Admin-only; returns 403 for non-admin callers."
}
],
"responses": {
"200": {
"description": "When `stream=false` (default), returns a JSON response. When `stream=true`, returns Server-Sent Events.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResponseResponse"
}
},
"text/event-stream": {
"schema": {
"type": "string",
"description": "Server-Sent Events stream following the OpenAI Responses API format.\n\nEach event is sent as `data: {json}\\n\\n` with the following event types:\n\n- `response.created` \u2014 initial response object (status: in_progress)\n- `response.in_progress` \u2014 status update\n- `response.output_item.added` \u2014 new output item added\n- `response.content_part.added` \u2014 new content part added\n- `response.output_text.delta` \u2014 incremental text delta\n- `response.completed` \u2014 final event with complete response object\n\nThe stream ends with `data: [DONE]\\n\\n`."
}
}
}
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Unauthorized"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Not Found"
},
"422": {
"description": "Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically."
},
"425": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Too Early"
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Internal Server Error"
},
"501": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Not Implemented"
},
"502": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Bad Gateway"
}
}
},
"delete": {
"tags": [
"Responses"
],
"summary": "Delete Response Endpoint",
"description": "Handle DELETE /v1/responses/{response_id} - delete stored response.\n\nIf the answer is not found, return 200 anyways.",
"operationId": "delete_response_endpoint_v1_responses__response_id__delete",
"security": [
{
"HTTPBearer": []
}
],
"parameters": [
{
"name": "response_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Response Id"
}
},
{
"name": "hard_delete",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"default": false,
"title": "Hard Delete"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Unauthorized"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Not Found"
},
"422": {
"description": "Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically."
},
"425": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Too Early"
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Internal Server Error"
},
"501": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Not Implemented"
},
"502": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Bad Gateway"
}
}
},
"patch": {
"tags": [
"Responses"
],
"summary": "Update Response Endpoint",
"description": "Handle PATCH /v1/responses/{response_id} - update a stored response.",
"operationId": "update_response_endpoint_v1_responses__response_id__patch",
"security": [
{
"HTTPBearer": []
}
],
"parameters": [
{
"name": "response_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Response Id"
}
},
{
"name": "recovery_from_delete",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"default": false,
"title": "Recovery From Delete"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResponseResponse"
}
}
}
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Unauthorized"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Not Found"
},
"422": {
"description": "Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically."
},
"425": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Too Early"
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Internal Server Error"
},
"501": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Not Implemented"
},
"502": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Bad Gateway"
}
}
}
},
"/v1/check": {
"post": {
"tags": [
"Guardrails"
],
"summary": "Post Check Endpoint",
"description": "Check content against guardrails for an application.",
"operationId": "post_check_endpoint_v1_check_post",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CheckRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CheckResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically."
},
"425": {
"description": "Too Early",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"501": {
"description": "Not Implemented",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"502": {
"description": "Bad Gateway",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"HTTPBearer": []
}
]
}
},
"/v1/conversations": {
"post": {
"tags": [
"Conversations"
],
"summary": "Create Conversation Endpoint",
"description": "Create a new conversation.",
"operationId": "create_conversation_endpoint_v1_conversations_post",
"security": [
{
"HTTPBearer": []
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"$ref": "#/components/schemas/CreateConversationRequest"
},
{
"type": "null"
}
],
"title": "Body"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConversationResponse"
}
}
}
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
# --- truncated at 32 KB (161 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/aleph-alpha/refs/heads/main/openapi/aleph-alpha-responses-openapi.json
This is an independent, third-party profile of Responses API (Stateful Responses), published by API Evangelist. We do not operate, host, resell, or support these APIs, and we are not affiliated with or endorsed by the company unless stated above. Everything here is built from publicly available information — the company's own site, developer portal, documentation, public repositories, and the specifications it publishes for public use. Nothing is obtained by breaching a system, defeating an access control, or using credentials.
The Kin Score and Agent Readiness rating are independently calculated assessments of a company's public API artifacts, scored against a published rubric. They are not certifications, endorsements, security assessments, or audits.
Corrections, re-scores, and removal are free — no partnership or purchase required, and you do not need to justify the request. A removed company is recorded as unrated, never scored zero for having asked. Acknowledgement within one business day; removal within two.
info@apievangelist.com
·
Read the full data-sourcing policy →
On a security or compliance team? Put security in the subject line and
you will get a person, not a form — we will tell you exactly which public URLs this profile was built from.