{ "openapi": "3.1.0", "info": { "title": "PromptMatrix API", "description": "Enterprise prompt governance infrastructure and CI/CD pipeline control plane for AI agent swarms.", "version": "1.1.0", "contact": { "name": "PromptMatrix Support", "email": "jachinchsaikiasonowal@gmail.com", "url": "https://promptmatrix.github.io" }, "license": { "name": "MIT", "url": "https://opensource.org/licenses/MIT" } }, "servers": [ { "url": "https://promptmatrixx.vercel.app", "description": "Production Managed Cloud" }, { "url": "http://localhost:8000", "description": "Local Self-Hosted Server" } ], "paths": { "/pm/serve/{prompt_key}": { "get": { "summary": "Serve Prompt", "description": "Runtime endpoint. Called by agents, n8n, LangChain, curl \u2014 anything.\nOptimised for low latency via Upstash + anyio threadpooling for DB calls.", "operationId": "serve_prompt_pm_serve__prompt_key__get", "parameters": [ { "name": "prompt_key", "in": "path", "required": true, "schema": { "type": "string", "title": "Prompt Key" } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "default": "text", "title": "Format" } }, { "name": "vars", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Vars" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/pm/serve/{prompt_key}/feedback": { "post": { "summary": "Serve Feedback", "description": "Backward compatibility endpoint for OSS SDKs to record telemetry in the SaaS backend.", "operationId": "serve_feedback_pm_serve__prompt_key__feedback_post", "parameters": [ { "name": "prompt_key", "in": "path", "required": true, "schema": { "type": "string", "title": "Prompt Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackIn" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/auth/register": { "post": { "tags": [ "auth" ], "summary": "Register", "operationId": "register_api_v1_auth_register_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterIn" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/auth/login": { "post": { "tags": [ "auth" ], "summary": "Login", "operationId": "login_api_v1_auth_login_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginIn" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/auth/logout": { "post": { "tags": [ "auth" ], "summary": "Logout", "description": "Invalidate a refresh token by adding its jti claim to a Redis blocklist.\nTTL matches the token's remaining lifetime \u2014 keys auto-expire, no cleanup needed.\nIf Redis is unavailable, logout is still acknowledged (fail-open for UX).", "operationId": "logout_api_v1_auth_logout_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogoutIn" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/auth/refresh": { "post": { "tags": [ "auth" ], "summary": "Refresh Token Endpoint", "operationId": "refresh_token_endpoint_api_v1_auth_refresh_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshIn" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/auth/me": { "get": { "tags": [ "auth" ], "summary": "Me", "operationId": "me_api_v1_auth_me_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api/v1/auth/change-password": { "post": { "tags": [ "auth" ], "summary": "Change Password", "description": "Change the authenticated user's password.\nUsed by the accept-invite flow (invited users log in with temp password, then set a real one).", "operationId": "change_password_api_v1_auth_change_password_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangePasswordIn" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api/v1/auth/verify-email": { "post": { "tags": [ "auth" ], "summary": "Verify Email", "description": "Verifies a user's email address using a signed JWT token.", "operationId": "verify_email_api_v1_auth_verify_email_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyEmailIn" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/prompts": { "get": { "tags": [ "prompts" ], "summary": "List Prompts", "operationId": "list_prompts_api_v1_prompts_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "environment_id", "in": "query", "required": true, "schema": { "type": "string", "title": "Environment Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "prompts" ], "summary": "Create Prompt", "operationId": "create_prompt_api_v1_prompts_post", "security": [ { "HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePromptIn" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/prompts/{prompt_id}": { "get": { "tags": [ "prompts" ], "summary": "Get Prompt", "operationId": "get_prompt_api_v1_prompts__prompt_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "prompt_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Prompt Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "prompts" ], "summary": "Delete Prompt", "operationId": "delete_prompt_api_v1_prompts__prompt_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "prompt_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Prompt Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/prompts/{prompt_id}/versions": { "get": { "tags": [ "prompts" ], "summary": "List Versions", "description": "List all versions for a prompt \u2014 used by the dashboard version history panel.", "operationId": "list_versions_api_v1_prompts__prompt_id__versions_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "prompt_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Prompt Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "prompts" ], "summary": "Create Version", "operationId": "create_version_api_v1_prompts__prompt_id__versions_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "prompt_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Prompt Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVersionIn" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/prompts/{prompt_id}/versions/{version_id}/submit": { "post": { "tags": [ "prompts" ], "summary": "Submit For Review", "operationId": "submit_for_review_api_v1_prompts__prompt_id__versions__version_id__submit_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "prompt_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Prompt Id" } }, { "name": "version_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Version Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitReviewIn" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/prompts/{prompt_id}/versions/{version_id}/approve": { "post": { "tags": [ "prompts" ], "summary": "Approve Version", "operationId": "approve_version_api_v1_prompts__prompt_id__versions__version_id__approve_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "prompt_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Prompt Id" } }, { "name": "version_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Version Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApproveIn" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/prompts/{prompt_id}/versions/{version_id}/reject": { "post": { "tags": [ "prompts" ], "summary": "Reject Version", "operationId": "reject_version_api_v1_prompts__prompt_id__versions__version_id__reject_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "prompt_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Prompt Id" } }, { "name": "version_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Version Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RejectIn" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/prompts/{prompt_id}/versions/{version_id}/rollback": { "post": { "tags": [ "prompts" ], "summary": "Rollback To Version", "operationId": "rollback_to_version_api_v1_prompts__prompt_id__versions__version_id__rollback_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "prompt_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Prompt Id" } }, { "name": "version_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Version Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/approvals": { "get": { "tags": [ "approvals" ], "summary": "List Approvals", "description": "List all pending approval requests for the org.", "operationId": "list_approvals_api_v1_approvals_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/approvals/queue": { "get": { "tags": [ "approvals" ], "summary": "List Approvals Queue", "description": "Alias for GET /api/v1/approvals \u2014 /queue suffix for dashboard compatibility.", "operationId": "list_approvals_queue_api_v1_approvals_queue_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/keys": { "get": { "tags": [ "keys" ], "summary": "List Keys", "operationId": "list_keys_api_v1_keys_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "environment_id", "in": "query", "required": true, "schema": { "type": "string", "title": "Environment Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "keys" ], "summary": "Create Key", "operationId": "create_key_api_v1_keys_post", "security": [ { "HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateKeyIn" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/keys/{key_id}": { "delete": { "tags": [ "keys" ], "summary": "Revoke Key", "operationId": "revoke_key_api_v1_keys__key_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Key Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/keys/{key_id}/rotate": { "post": { "tags": [ "keys" ], "summary": "Rotate Key", "operationId": "rotate_key_api_v1_keys__key_id__rotate_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Key Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/projects": { "get": { "tags": [ "projects" ], "summary": "List Projects", "operationId": "list_projects_api_v1_projects_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "HTTPBearer": [] } ] }, "post": { "tags": [ "projects" ], "summary": "Create Project", "description": "Create a new project with default or custom environments. Requires admin+ role.", "operationId": "create_project_api_v1_projects_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProjectIn" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api/v1/projects/{project_id}/environments": { "post": { "tags": [ "projects" ], "summary": "Create Environment", "description": "Add a new environment to an existing project. Requires admin+ role.", "operationId": "create_environment_api_v1_projects__project_id__environments_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEnvironmentIn" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "projects" ], "summary": "List Environments", "description": "List environments for a specific project (IDOR-protected).", "operationId": "list_environments_api_v1_projects__project_id__environments_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/orgs/me": { "get": { "tags": [ "orgs" ], "summary": "Get My Org", "description": "Returns the caller's current organisation and membership info.", "operationId": "get_my_org_api_v1_orgs_me_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api/v1/orgs/{org_id}/members": { "get": { "tags": [ "orgs" ], "summary": "List Members", "operationId": "list_members_api_v1_orgs__org_id__members_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Org Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "orgs" ], "summary": "Invite Member", "operationId": "invite_member_api_v1_orgs__org_id__members_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Org Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteIn" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/orgs/{org_id}/members/{user_id}": { "delete": { "tags": [ "orgs" ], "summary": "Remove Member", "operationId": "remove_member_api_v1_orgs__org_id__members__user_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Org Id" } }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/audit": { "get": { "tags": [ "audit" ], "summary": "List Audit", "operationId": "list_audit_api_v1_audit_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "resource_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Resource Type" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/evals/run": { "post": { "tags": [ "evals" ], "summary": "Run Eval", "operationId": "run_eval_api_v1_evals_run_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunEvalIn" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api/v1/evals/keys": { "get": { "tags": [ "evals" ], "summary": "List Eval Keys", "operationId": "list_eval_keys_api_v1_evals_keys_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "evals" ], "summary": "Save Eval Key", "operationId": "save_eval_key_api_v1_evals_keys_post", "security": [ { "HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveKeyIn" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/evals/keys/{key_id}": { "delete": { "tags": [ "evals" ], "summary": "Delete Eval Key", "operationId": "delete_eval_key_api_v1_evals_keys__key_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Key Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/webhooks/razorpay": { "post": { "tags": [ "webhooks" ], "summary": "Razorpay Webhook", "description": "Razorpay webhook endpoint.\n\nRequired Razorpay events to subscribe to:\n - payment.captured (one-time Founding Member purchase)", "operationId": "razorpay_webhook_api_v1_webhooks_razorpay_post", "parameters": [ { "name": "X-Razorpay-Signature", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Razorpay-Signature" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agent/evals": { "post": { "tags": [ "agent-evals" ], "summary": "Submit Agent Eval", "operationId": "submit_agent_eval_api_v1_agent_evals_post", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentEvalIn" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "agent-evals" ], "summary": "List Evals", "operationId": "list_evals_api_v1_agent_evals_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "environment_id", "in": "query", "required": true, "schema": { "type": "string", "title": "Environment Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 200, "title": "Limit" } }, { "name": "source", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source" } }, { "name": "pass_filter", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pass Filter" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agent/evals/prompt": { "get": { "tags": [ "agent-evals" ], "summary": "Get Prompt Evals", "operationId": "get_prompt_evals_api_v1_agent_evals_prompt_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "key", "in": "query", "required": true, "schema": { "type": "string", "title": "Key" } }, { "name": "environment_id", "in": "query", "required": true, "schema": { "type": "string", "title": "Environment Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/agent/prompts": { "get": { "tags": [ "agent-evals" ], "summary": "Agent Get Prompts", "operationId": "agent_get_prompts_api_v1_agent_prompts_get", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/billing/checkout": { "get": { "tags": [ "billing" ], "summary": "Get Checkout Url", "description": "Returns a Razorpay Payment Link for the requested plan.\n\nIMPORTANT: Before returning the URL we store the user's email as\norg.billing_email so the webhook can find the org by email as a\nfallback when Razorpay Payment Pages don't populate notes.org_id.", "operationId": "get_checkout_url_api_v1_billing_checkout_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "plan", "in": "query", "required": true, "schema": { "type": "string", "title": "Plan" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/billing/status": { "get": { "tags": [ "billing" ], "summary": "Billing Status", "description": "Returns the current billing plan and limits for the user's org.", "operationId": "billing_status_api_v1_billing_status_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api/v1/billing/usage": { "get": { "tags": [ "billing" ], "summary": "Billing Usage", "description": "Returns usage of limits (seats, prompts, API calls) for the user's org.", "operationId": "billing_usage_api_v1_billing_usage_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api/v1/public/stats": { "get": { "tags": [ "public" ], "summary": "Get Stats", "description": "Live counter stats \u2014 used by landing page to display:\n - Remaining founding member spots\n - Total waitlist signups by tier\n\nCalled by the landing page every 30 seconds via JS polling.\nRate limited: 10 requests/minute per IP to prevent DB hammering.", "operationId": "get_stats_api_v1_public_stats_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/public/waitlist": { "post": { "tags": [ "public" ], "summary": "Join Waitlist", "description": "Capture waitlist interest for non-founding tiers.\nDuplicate emails are silently ignored (idempotent).\nRate limited: 5 requests/minute per IP to prevent DB spam.", "operationId": "join_waitlist_api_v1_public_waitlist_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WaitlistIn" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/auth/forgot-password": { "post": { "tags": [ "auth" ], "summary": "Forgot Password", "description": "Initiates password reset. Always returns 200 \u2014 never reveals\nwhether the email exists (prevents user enumeration).", "operationId": "forgot_password_api_v1_auth_forgot_password_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForgotPasswordIn" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/auth/reset-password": { "post": { "tags": [ "auth" ], "summary": "Reset Password", "description": "Validates token and sets new password. Token is single-use\n(jti is blocklisted in Redis after first use).", "operationId": "reset_password_api_v1_auth_reset_password_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetPasswordIn" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/status": { "get": { "summary": "Status", "description": "Health check endpoint. Probes the database with a lightweight SELECT 1.\nReturns db_status so uptime monitors catch DB connectivity failures early.\nProduction-safe: never leaks env name or error details to the outside.", "operationId": "status_api_status_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/health": { "get": { "summary": "Health", "description": "Alias for /api/status \u2014 satisfies Vercel uptime monitors and load balancer probes.", "operationId": "health_health_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/status/public": { "get": { "summary": "Public Status", "description": "Public live-counter endpoint \u2014 no auth required.\nSafe: returns only aggregate counts, zero PII, zero internal config.\n\nIntended uses:\n - Embed in launch tweets: '\ud83d\udfe2 PromptMatrix Founders: 3/100 claimed'\n - GitHub README badge via shields.io JSON endpoint\n - Product Hunt launch post counter\n - External monitoring scripts\n\nResponse:\n {\"founders\": 3, \"total\": 100, \"remaining\": 97, \"sold_out\": false,\n \"oss\": \"https://github.com/PromptMatrix/Promptmatrix\"}", "operationId": "public_status_api_status_public_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } } }, "components": { "schemas": { "AgentEvalIn": { "properties": { "prompt_key": { "type": "string", "title": "Prompt Key" }, "score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Score" }, "rationale": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Rationale" }, "criteria": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Criteria" }, "strengths": { "anyOf": [ { "items": {}, "type": "array" }, { "type": "null" } ], "title": "Strengths" }, "issues": { "anyOf": [ { "items": {}, "type": "array" }, { "type": "null" } ], "title": "Issues" }, "latency_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Latency Ms" }, "tokens_in": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tokens In" }, "tokens_out": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tokens Out" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model" }, "success": { "type": "boolean", "title": "Success", "default": true }, "source": { "type": "string", "title": "Source", "default": "agent" }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Session Id" } }, "type": "object", "required": [ "prompt_key" ], "title": "AgentEvalIn" }, "ApproveIn": { "properties": { "note": { "type": "string", "title": "Note", "default": "" } }, "type": "object", "title": "ApproveIn" }, "ChangePasswordIn": { "properties": { "current_password": { "type": "string", "title": "Current Password" }, "new_password": { "type": "string", "title": "New Password" } }, "type": "object", "required": [ "current_password", "new_password" ], "title": "ChangePasswordIn" }, "CreateEnvironmentIn": { "properties": { "name": { "type": "string", "title": "Name" }, "display_name": { "type": "string", "title": "Display Name", "default": "" }, "color": { "type": "string", "title": "Color", "default": "#607d8b" }, "is_protected": { "type": "boolean", "title": "Is Protected", "default": false }, "eval_pass_threshold": { "type": "number", "title": "Eval Pass Threshold", "default": 0.0 } }, "type": "object", "required": [ "name" ], "title": "CreateEnvironmentIn" }, "CreateKeyIn": { "properties": { "environment_id": { "type": "string", "title": "Environment Id" }, "name": { "type": "string", "title": "Name" } }, "type": "object", "required": [ "environment_id", "name" ], "title": "CreateKeyIn" }, "CreateProjectIn": { "properties": { "name": { "type": "string", "title": "Name" }, "environments": { "items": { "type": "string" }, "type": "array", "title": "Environments", "default": [ "production", "staging", "development" ] } }, "type": "object", "required": [ "name" ], "title": "CreateProjectIn" }, "CreatePromptIn": { "properties": { "environment_id": { "type": "string", "title": "Environment Id" }, "key": { "type": "string", "title": "Key" }, "content": { "type": "string", "maxLength": 65536, "title": "Content" }, "description": { "type": "string", "title": "Description", "default": "" }, "commit_message": { "type": "string", "title": "Commit Message", "default": "Initial version" }, "tags": { "items": {}, "type": "array", "title": "Tags", "default": [] } }, "type": "object", "required": [ "environment_id", "key", "content" ], "title": "CreatePromptIn" }, "CreateVersionIn": { "properties": { "content": { "type": "string", "maxLength": 65536, "title": "Content" }, "commit_message": { "type": "string", "title": "Commit Message", "default": "" } }, "type": "object", "required": [ "content" ], "title": "CreateVersionIn" }, "FeedbackIn": { "properties": { "version_id": { "type": "string", "title": "Version Id" }, "outcome": { "type": "string", "title": "Outcome", "default": "success" }, "latency_ms": { "type": "integer", "title": "Latency Ms", "default": 0 }, "tokens_used": { "type": "integer", "title": "Tokens Used", "default": 0 }, "llm_latency_ms": { "type": "integer", "title": "Llm Latency Ms", "default": 0 }, "metadata": { "additionalProperties": true, "type": "object", "title": "Metadata", "default": {} } }, "type": "object", "required": [ "version_id" ], "title": "FeedbackIn" }, "ForgotPasswordIn": { "properties": { "email": { "type": "string", "title": "Email" } }, "type": "object", "required": [ "email" ], "title": "ForgotPasswordIn" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "InviteIn": { "properties": { "email": { "type": "string", "title": "Email" }, "role": { "type": "string", "title": "Role", "default": "editor" } }, "type": "object", "required": [ "email" ], "title": "InviteIn" }, "LoginIn": { "properties": { "email": { "type": "string", "title": "Email" }, "password": { "type": "string", "title": "Password" } }, "type": "object", "required": [ "email", "password" ], "title": "LoginIn" }, "LogoutIn": { "properties": { "refresh_token": { "type": "string", "title": "Refresh Token" } }, "type": "object", "required": [ "refresh_token" ], "title": "LogoutIn" }, "RefreshIn": { "properties": { "refresh_token": { "type": "string", "title": "Refresh Token" } }, "type": "object", "required": [ "refresh_token" ], "title": "RefreshIn" }, "RegisterIn": { "properties": { "email": { "type": "string", "title": "Email" }, "password": { "type": "string", "title": "Password" }, "full_name": { "type": "string", "title": "Full Name", "default": "" }, "org_name": { "type": "string", "title": "Org Name", "default": "" }, "tier_intent": { "type": "string", "title": "Tier Intent", "default": "" } }, "type": "object", "required": [ "email", "password" ], "title": "RegisterIn" }, "RejectIn": { "properties": { "reason": { "type": "string", "title": "Reason" } }, "type": "object", "required": [ "reason" ], "title": "RejectIn" }, "ResetPasswordIn": { "properties": { "token": { "type": "string", "title": "Token" }, "new_password": { "type": "string", "title": "New Password" } }, "type": "object", "required": [ "token", "new_password" ], "title": "ResetPasswordIn" }, "RunEvalIn": { "properties": { "version_id": { "type": "string", "title": "Version Id" }, "provider": { "type": "string", "title": "Provider", "default": "anthropic" }, "model": { "type": "string", "title": "Model", "default": "claude-sonnet-4-6" }, "api_key": { "type": "string", "title": "Api Key", "default": "" }, "test_input": { "type": "string", "title": "Test Input", "default": "" }, "eval_type": { "type": "string", "title": "Eval Type", "default": "llm_judge" } }, "type": "object", "required": [ "version_id" ], "title": "RunEvalIn" }, "SaveKeyIn": { "properties": { "provider": { "type": "string", "title": "Provider" }, "api_key": { "type": "string", "title": "Api Key" }, "label": { "type": "string", "title": "Label", "default": "" } }, "type": "object", "required": [ "provider", "api_key" ], "title": "SaveKeyIn" }, "SubmitReviewIn": { "properties": { "note": { "type": "string", "title": "Note", "default": "" } }, "type": "object", "title": "SubmitReviewIn" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "VerifyEmailIn": { "properties": { "token": { "type": "string", "title": "Token" } }, "type": "object", "required": [ "token" ], "title": "VerifyEmailIn" }, "WaitlistIn": { "properties": { "email": { "type": "string", "title": "Email" }, "tier": { "type": "string", "title": "Tier" }, "name": { "type": "string", "title": "Name", "default": "" } }, "type": "object", "required": [ "email", "tier" ], "title": "WaitlistIn" } }, "securitySchemes": { "HTTPBearer": { "type": "http", "scheme": "bearer" } } } }