{
  "openapi": "3.0.3",
  "info": {
    "title": "EmpatiQ Persona API",
    "version": "1.0.0",
    "description": "Reference for the existing account-scoped persona catalog and text chat endpoints. Your application supplies persona chat history. For emotion analysis, the full Emery experience with memory and tools, or digital twin creation, contact the EmpatiQ team to agree your integration URL, credentials, and contract."
  },
  "servers": [
    {
      "url": "/",
      "description": "Use the origin of your EmpatiQ deployment"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "tags": [
    {
      "name": "Personas"
    },
    {
      "name": "Chat"
    },
    {
      "name": "Embed"
    }
  ],
  "paths": {
    "/api/platform/v1/personas": {
      "get": {
        "operationId": "listPersonas",
        "tags": [
          "Personas"
        ],
        "summary": "List active personas owned by the API account",
        "responses": {
          "200": {
            "description": "Active persona catalog. System prompts are not returned.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "personas"
                  ],
                  "properties": {
                    "personas": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Persona"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Failed to fetch personas",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/platform/v1/personas/{id}/chat": {
      "post": {
        "operationId": "chatWithPersona",
        "tags": [
          "Chat"
        ],
        "summary": "Send a text message to an account-owned persona",
        "description": "Returns a complete JSON reply without streaming. Replay prior user and assistant turns in conversationHistory. Successful calls consume allowance in whole minutes, rounded up per request with a minimum measured duration of six seconds.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Persona UUID owned by this API account",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChatRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Generated persona reply",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChatResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized or Invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Minutes limit exhausted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Persona not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Failed to chat",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/platform/embed/{userId}/personas": {
      "get": {
        "operationId": "listPublicPersonas",
        "tags": [
          "Embed"
        ],
        "summary": "List public persona metadata for a widget",
        "description": "No API key needed. This catalog grants no chat access. Send chat messages through your own backend with an API key.",
        "security": [],
        "parameters": [
          {
            "name": "userId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Public personas and display flags",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "personas",
                    "showBranding",
                    "hasMinutes"
                  ],
                  "properties": {
                    "personas": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Persona"
                      }
                    },
                    "showBranding": {
                      "type": "boolean"
                    },
                    "hasMinutes": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Failed to fetch embed personas",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "emp_<32 hexadecimal characters>",
        "description": "Keep the key on your server. API keys cannot create other API keys."
      }
    },
    "schemas": {
      "Persona": {
        "type": "object",
        "required": [
          "id",
          "name",
          "description",
          "avatar_theme",
          "avatar_url",
          "voice_id",
          "is_active"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "avatar_theme": {
            "type": "string"
          },
          "avatar_url": {
            "type": "string",
            "nullable": true
          },
          "voice_id": {
            "type": "string",
            "nullable": true,
            "description": "Metadata only; voice is not provided by this API"
          },
          "is_active": {
            "type": "boolean"
          }
        }
      },
      "ChatRequest": {
        "type": "object",
        "required": [
          "message"
        ],
        "properties": {
          "message": {
            "type": "string",
            "description": "The new user message. Send a nonempty string.",
            "example": "I want to talk about what happened."
          },
          "conversationHistory": {
            "type": "array",
            "default": [],
            "description": "Prior turns, oldest first, excluding the new message",
            "items": {
              "$ref": "#/components/schemas/ConversationTurn"
            }
          }
        }
      },
      "ConversationTurn": {
        "type": "object",
        "required": [
          "role",
          "content"
        ],
        "properties": {
          "role": {
            "type": "string",
            "enum": [
              "user",
              "assistant"
            ]
          },
          "content": {
            "type": "string"
          }
        }
      },
      "ChatResponse": {
        "type": "object",
        "required": [
          "message",
          "success"
        ],
        "properties": {
          "message": {
            "type": "string"
          },
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}