{ "openapi": "3.1.0", "info": { "title": "PromptLens Product API", "version": "1.0.0-draft.1", "description": "Retrieve saved prompts with prompt-scoped keys and manage prompts, evaluations, and organizations with OAuth.", "license": { "name": "Proprietary", "url": "https://www.promptlens.io/terms" } }, "servers": [ { "url": "https://www.promptlens.io", "description": "Canonical public API origin." } ], "tags": [ { "name": "Integration", "description": "Read-only prompt retrieval for applications." }, { "name": "Management", "description": "User-based OAuth API for account and product management." } ], "paths": { "/api/v1/organizations/{organizationId}/evals/{evaluationId}/resume": { "post": { "operationId": "resume_evaluation", "summary": "resume evaluation", "description": "Explicitly resume unfinished work on a paused evaluation using its original frozen inputs. Requires writable organization access and current plan and usage eligibility. Completed cases are not repeated.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": false, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "name": "evaluationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent evaluationId; selected organization must be authorized for the current user." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Evaluation" } } } } }, "x-confirmation-required": true } }, "/api/v1/prompts/{promptId}": { "get": { "operationId": "retrieve_prompt", "summary": "Retrieve a saved prompt", "description": "Retrieve saved prompt configuration for your application. Omit both selectors to resolve production. Supply either label or version, never both; reject duplicate, empty, or unknown parameters. Authenticate and authorize before cache validation. The next server request sees a completed label move, including rollback. Exact versions are immutable. Missing/unassigned labels never fall back. A successful 200 or authenticated 304 for an archived prompt records activity. Retrieval never executes a model.", "tags": ["Integration"], "x-implementation-status": "implemented", "security": [ { "RetrievalKey": [] } ], "parameters": [ { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "label", "in": "query", "schema": { "type": "string", "pattern": "^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$" } }, { "name": "version", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "If-None-Match", "in": "header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrievedPrompt" } } }, "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" }, "description": "private, no-cache; revalidate with the server before using a cached response." }, "Vary": { "schema": { "type": "string" }, "description": "Authorization" } } }, "304": { "description": "Unchanged. No response body; caller remains authorized.", "headers": { "ETag": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string" }, "description": "private, no-cache; revalidate with the server before using a cached response." }, "Vary": { "schema": { "type": "string" }, "description": "Authorization" } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/me": { "get": { "operationId": "get_profile", "summary": "get profile", "description": "Uses the selected organization and the authenticated user’s current permissions. Applies the same setup and archive rules as the dashboard.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": false, "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/me/default-organization": { "put": { "operationId": "set_default_organization", "summary": "set default organization", "description": "Remember the user's account default as an initial organization suggestion; null clears it. This preference does not change an established local CLI organization context or an MCP action's explicit organization target. Every organization-scoped MCP tool invocation supplies organizationId. An inaccessible default causes an explicit choose-organization error; never silently switch to another organization.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": false, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "organizationId": { "type": ["string", "null"] } }, "required": ["organizationId"], "additionalProperties": false } } } } } }, "/api/v1/organizations": { "get": { "operationId": "list_organizations", "summary": "list organizations", "description": "Uses the selected organization and the authenticated user’s current permissions. Applies the same setup and archive rules as the dashboard.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": false, "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationPage" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "create_organization", "summary": "create organization", "description": "User-based OAuth allows organization creation without an existing selected organization. The authenticated user becomes its admin; existing onboarding rules apply.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": false, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": ["name"], "additionalProperties": false } } } } } }, "/api/v1/organizations/{organizationId}": { "get": { "operationId": "get_organization", "summary": "get organization", "description": "Uses the selected organization and the authenticated user’s current permissions. Applies the same setup and archive rules as the dashboard.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": false, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "patch": { "operationId": "rename_organization", "summary": "rename organization", "description": "Uses the selected organization and the authenticated user’s current permissions. Applies the same setup and archive rules as the dashboard.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": true, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": ["name"], "additionalProperties": false } } } } } }, "/api/v1/organizations/{organizationId}/deletion-link": { "post": { "operationId": "get_organization_deletion_link", "summary": "get organization deletion link", "description": "Return an authenticated dashboard destination for final organization deletion. OAuth cannot delete an organization directly.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": true, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardLink" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/organizations/{organizationId}/members": { "get": { "operationId": "list_members", "summary": "list members", "description": "Uses the selected organization and the authenticated user’s current permissions. Applies the same setup and archive rules as the dashboard.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": false, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberPage" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/organizations/{organizationId}/members/{userId}": { "patch": { "operationId": "change_member_role", "summary": "change member role", "description": "Requires a current admin. Preserve at least one admin and enforce Clerk membership and plan limits.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": true, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent userId; selected organization must be authorized for the current user." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Member" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": ["admin", "member"] } }, "required": ["role"], "additionalProperties": false } } } }, "x-confirmation-required": true }, "delete": { "operationId": "remove_member", "summary": "remove member", "description": "Remove a member under current admin rules. Membership loss revokes their management access, but does not revoke organization-owned retrieval keys.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": true, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent userId; selected organization must be authorized for the current user." } ], "responses": { "204": { "description": "Completed" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "x-confirmation-required": true } }, "/api/v1/organizations/{organizationId}/invitations": { "get": { "operationId": "list_invitations", "summary": "list invitations", "description": "Uses the selected organization and the authenticated user’s current permissions. Applies the same setup and archive rules as the dashboard.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": false, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationPage" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "invite_member", "summary": "invite member", "description": "Uses the selected organization and the authenticated user’s current permissions. Applies the same setup and archive rules as the dashboard.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": true, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invitation" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "role": { "type": "string", "enum": ["admin", "member"] } }, "required": ["email", "role"], "additionalProperties": false } } } } } }, "/api/v1/organizations/{organizationId}/invitations/{invitationId}": { "delete": { "operationId": "revoke_invitation", "summary": "revoke invitation", "description": "Uses the selected organization and the authenticated user’s current permissions. Applies the same setup and archive rules as the dashboard.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": true, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "name": "invitationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent invitationId; selected organization must be authorized for the current user." } ], "responses": { "204": { "description": "Completed" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "x-confirmation-required": true } }, "/api/v1/organizations/{organizationId}/prompts": { "get": { "operationId": "list_prompts", "summary": "list prompts", "description": "Uses the selected organization and the authenticated user’s current permissions. Applies the same setup and archive rules as the dashboard.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": false, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "archived", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromptPage" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "create_prompt", "summary": "create prompt", "description": "Create one named prompt with a private user draft, one ordered dataset, and unassigned staging/production labels. No version 1 is available before successful baseline initialization.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": false, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Prompt" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePrompt" } } } } } }, "/api/v1/organizations/{organizationId}/prompts/{promptId}": { "get": { "operationId": "get_prompt", "summary": "get prompt", "description": "Uses the selected organization and the authenticated user’s current permissions. Applies the same setup and archive rules as the dashboard.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": false, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent promptId; selected organization must be authorized for the current user." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Prompt" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "patch": { "operationId": "rename_prompt", "summary": "rename prompt", "description": "Uses the selected organization and the authenticated user’s current permissions. Applies the same setup and archive rules as the dashboard.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": false, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent promptId; selected organization must be authorized for the current user." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Prompt" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": ["name"], "additionalProperties": false } } } } } }, "/api/v1/organizations/{organizationId}/prompts/{promptId}/archive": { "post": { "operationId": "archive_prompt", "summary": "archive prompt", "description": "Make this prompt read-only, retaining saved versions, labels, keys and retrieval. Later successful retrieval/revalidation raises an archived-use warning.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": false, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent promptId; selected organization must be authorized for the current user." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Prompt" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "x-confirmation-required": true } }, "/api/v1/organizations/{organizationId}/prompts/{promptId}/restore": { "post": { "operationId": "restore_prompt", "summary": "restore prompt", "description": "Uses the selected organization and the authenticated user’s current permissions. Applies the same setup and archive rules as the dashboard.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": false, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent promptId; selected organization must be authorized for the current user." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Prompt" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/organizations/{organizationId}/prompts/{promptId}/draft": { "get": { "operationId": "get_personal_draft", "summary": "get personal draft", "description": "Only the authenticated user’s draft. Dashboard, CLI and MCP share this same personal draft.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": false, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent promptId; selected organization must be authorized for the current user." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Draft" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "put": { "operationId": "update_personal_draft", "summary": "update personal draft", "description": "Compare-and-swap revision. A stale write fails with draft_conflict and preserves existing content. Never silently overwrite another window or tool.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": false, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent promptId; selected organization must be authorized for the current user." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Draft" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftWrite" } } } } } }, "/api/v1/organizations/{organizationId}/prompts/{promptId}/draft/discard": { "post": { "operationId": "discard_personal_draft", "summary": "discard personal draft", "description": "Uses the selected organization and the authenticated user’s current permissions. Applies the same setup and archive rules as the dashboard.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": false, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent promptId; selected organization must be authorized for the current user." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Draft" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revision": { "type": "integer", "minimum": 0 } }, "required": ["revision"], "additionalProperties": false } } } }, "x-confirmation-required": true } }, "/api/v1/organizations/{organizationId}/prompts/{promptId}/initialize": { "post": { "operationId": "initialize_baseline", "summary": "initialize baseline", "description": "Freeze the setup draft and selected cases. On completion with all cases scored and no pending review or execution errors, atomically publish immutable version 1 to staging and production. Assertion failures do not block initialization. Retried setup cannot publish a different snapshot accidentally.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": false, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent promptId; selected organization must be authorized for the current user." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Evaluation" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetupStart" } } } }, "x-confirmation-required": true } }, "/api/v1/organizations/{organizationId}/prompts/{promptId}/versions": { "get": { "operationId": "list_versions", "summary": "list versions", "description": "Uses the selected organization and the authenticated user’s current permissions. Applies the same setup and archive rules as the dashboard.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": false, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent promptId; selected organization must be authorized for the current user." }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionPage" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "save_version", "summary": "save version", "description": "Save an immutable version from the current user’s exact draft revision. Requires completed setup and an active prompt. No evaluation requirement and no automatic label changes. Idempotent replay returns the original version.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": false, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent promptId; selected organization must be authorized for the current user." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Version" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "draftRevision": { "type": "integer", "minimum": 0 } }, "required": ["draftRevision"], "additionalProperties": false } } } } } }, "/api/v1/organizations/{organizationId}/prompts/{promptId}/versions/{versionId}": { "get": { "operationId": "get_version", "summary": "get version", "description": "Uses the selected organization and the authenticated user’s current permissions. Applies the same setup and archive rules as the dashboard.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": false, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent promptId; selected organization must be authorized for the current user." }, { "name": "versionId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent versionId; selected organization must be authorized for the current user." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Version" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/organizations/{organizationId}/prompts/{promptId}/versions/{versionId}/coverage": { "get": { "operationId": "get_version_coverage", "summary": "get version coverage", "description": "Report matching completed evidence, current and last evaluated dataset sizes, and stale/quick-only coverage. A same-count content edit can make evidence stale. Quick coverage ignores changes outside the first 10 cases.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": false, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent promptId; selected organization must be authorized for the current user." }, { "name": "versionId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent versionId; selected organization must be authorized for the current user." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Coverage" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/organizations/{organizationId}/prompts/{promptId}/labels": { "get": { "operationId": "list_labels", "summary": "list labels", "description": "Uses the selected organization and the authenticated user’s current permissions. Applies the same setup and archive rules as the dashboard.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": false, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent promptId; selected organization must be authorized for the current user." }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelPage" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "create_label", "summary": "create label", "description": "Uses the selected organization and the authenticated user’s current permissions. Applies the same setup and archive rules as the dashboard.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": false, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent promptId; selected organization must be authorized for the current user." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Label" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$" } }, "required": ["name"], "additionalProperties": false } } } } } }, "/api/v1/organizations/{organizationId}/prompts/{promptId}/labels/{labelName}": { "put": { "operationId": "assign_label", "summary": "assign label", "description": "Compare label revision, including ABA changes. Production cannot be unassigned after setup. Return published=false and structured warnings plus acknowledgment when production lacks current coverage. Retry with the context-bound acknowledgment to Proceed Anyway. Reject stale acknowledgment. Staging/custom labels do not require evaluations; default labels cannot be renamed/deleted.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": false, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent promptId; selected organization must be authorized for the current user." }, { "name": "labelName", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent labelName; selected organization must be authorized for the current user." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Publication" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelMove" } } } }, "x-confirmation-required": true }, "patch": { "operationId": "rename_label", "summary": "rename label", "description": "Rename only a custom label with a matching revision. Default production/staging labels are permanent. The old name subsequently returns label_not_found.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": false, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent promptId; selected organization must be authorized for the current user." }, { "name": "labelName", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent labelName; selected organization must be authorized for the current user." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Label" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$" }, "revision": { "type": "integer", "minimum": 0 } }, "required": ["name", "revision"], "additionalProperties": false } } } } }, "delete": { "operationId": "delete_label", "summary": "delete label", "description": "Delete a custom label using If-Match revision; default labels cannot be deleted.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": false, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent promptId; selected organization must be authorized for the current user." }, { "name": "labelName", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent labelName; selected organization must be authorized for the current user." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Completed" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "x-confirmation-required": true } }, "/api/v1/organizations/{organizationId}/prompts/{promptId}/dataset": { "get": { "operationId": "get_dataset", "summary": "get dataset", "description": "Uses the selected organization and the authenticated user’s current permissions. Applies the same setup and archive rules as the dashboard.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": false, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent promptId; selected organization must be authorized for the current user." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dataset" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/organizations/{organizationId}/prompts/{promptId}/dataset/import": { "post": { "operationId": "import_dataset", "summary": "import dataset", "description": "Append by default; replace only when explicitly requested. Validate every row and deduplicate exact input/expectedOutput pairs against existing rows and within the request in first-occurrence order. Reject the entire request if any row is invalid or unique additions exceed capacity. Error details include row errors, currentCount, availableCapacity and requestedAddition. Free capacity 10, Pro 500. Existing rows are never truncated on downgrade.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": false, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent promptId; selected organization must be authorized for the current user." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportResult" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetImport" } } } }, "x-confirmation-required": true } }, "/api/v1/organizations/{organizationId}/prompts/{promptId}/dataset/cases/{caseId}": { "put": { "operationId": "update_dataset_case", "summary": "update dataset case", "description": "Uses the selected organization and the authenticated user’s current permissions. Applies the same setup and archive rules as the dashboard.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": false, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent promptId; selected organization must be authorized for the current user." }, { "name": "caseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent caseId; selected organization must be authorized for the current user." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetRow" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revision": { "type": "integer", "minimum": 0 }, "row": { "$ref": "#/components/schemas/DatasetRowInput" } }, "required": ["revision", "row"], "additionalProperties": false } } } }, "x-confirmation-required": true }, "delete": { "operationId": "delete_dataset_case", "summary": "delete dataset case", "description": "Uses the selected organization and the authenticated user’s current permissions. Applies the same setup and archive rules as the dashboard.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": false, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent promptId; selected organization must be authorized for the current user." }, { "name": "caseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent caseId; selected organization must be authorized for the current user." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Completed" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "x-confirmation-required": true } }, "/api/v1/organizations/{organizationId}/prompts/{promptId}/dataset/order": { "put": { "operationId": "reorder_dataset", "summary": "reorder dataset", "description": "Provide every current case ID exactly once. Quick runs use the first 10 cases of the resulting order.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": false, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent promptId; selected organization must be authorized for the current user." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dataset" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revision": { "type": "integer", "minimum": 0 }, "caseIds": { "type": "array", "items": { "type": "string" } } }, "required": ["revision", "caseIds"], "additionalProperties": false } } } }, "x-confirmation-required": true } }, "/api/v1/organizations/{organizationId}/evals": { "get": { "operationId": "list_evaluations", "summary": "list evaluations", "description": "Uses the selected organization and the authenticated user’s current permissions. Applies the same setup and archive rules as the dashboard.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": false, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "promptId", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "running", "paused", "completed", "failed", "cancelled" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationPage" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/organizations/{organizationId}/prompts/{promptId}/evals": { "post": { "operationId": "start_evaluation", "summary": "start evaluation", "description": "Pin current production at request acceptance and freeze the latest ordered dataset, saved version/model/settings, and scoring policy. Quick uses first 10 (all available on Free); comprehensive uses all (Pro only). Reuse most recent compatible completed production evidence by default, otherwise evaluate both sides in parallel. rerun_both forces fresh evidence. No model/settings overrides for saved versions. Start requests are idempotent to prevent duplicate charges.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": false, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent promptId; selected organization must be authorized for the current user." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComparisonStart" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationStart" } } } }, "x-confirmation-required": true } }, "/api/v1/organizations/{organizationId}/evals/{evaluationId}": { "get": { "operationId": "get_evaluation", "summary": "get evaluation", "description": "Uses the selected organization and the authenticated user’s current permissions. Applies the same setup and archive rules as the dashboard.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": false, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "name": "evaluationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent evaluationId; selected organization must be authorized for the current user." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Evaluation" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/organizations/{organizationId}/evals/{evaluationId}/results": { "get": { "operationId": "list_evaluation_results", "summary": "list evaluation results", "description": "Uses the selected organization and the authenticated user’s current permissions. Applies the same setup and archive rules as the dashboard.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": false, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "name": "evaluationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent evaluationId; selected organization must be authorized for the current user." }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationResultPage" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/organizations/{organizationId}/evals/{evaluationId}/cancel": { "post": { "operationId": "cancel_evaluation", "summary": "cancel evaluation", "description": "Stop pending work, retain partial results, mark cancelled. In-flight calls may be charged. Cancelled runs provide no completed coverage and cannot initialize baseline.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": false, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "name": "evaluationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent evaluationId; selected organization must be authorized for the current user." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Evaluation" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "x-confirmation-required": true } }, "/api/v1/organizations/{organizationId}/evals/{evaluationId}/retry": { "post": { "operationId": "retry_evaluation_side", "summary": "retry evaluation side", "description": "Retry only a failed/cancelled side with its exact frozen inputs and pinned production version. Keep completed counterpart evidence and charges. To change inputs, start a new comparison.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": false, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "name": "evaluationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent evaluationId; selected organization must be authorized for the current user." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Evaluation" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "side": { "type": "string", "enum": ["candidate", "production"] } }, "required": ["side"], "additionalProperties": false } } } }, "x-confirmation-required": true } }, "/api/v1/organizations/{organizationId}/evals/{evaluationId}/reviews": { "post": { "operationId": "review_evaluation_results", "summary": "review evaluation results", "description": "Current authorized users and their OAuth clients may review outputs. Record user and OAuth client identity from the verified token. Do not claim a human reviewed agent-submitted decisions. Calibration accepts generated or corrected expectations; scored review marks output correct/incorrect.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": false, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "name": "evaluationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent evaluationId; selected organization must be authorized for the current user." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Evaluation" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reviews": { "type": "array", "items": { "$ref": "#/components/schemas/Review" }, "minItems": 1, "maxItems": 100 } }, "required": ["reviews"], "additionalProperties": false } } } }, "x-confirmation-required": true } }, "/api/v1/organizations/{organizationId}/prompts/{promptId}/keys": { "get": { "operationId": "list_retrieval_keys", "summary": "list retrieval keys", "description": "Uses the selected organization and the authenticated user’s current permissions. Applies the same setup and archive rules as the dashboard.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": false, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent promptId; selected organization must be authorized for the current user." }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyPage" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "create_retrieval_key", "summary": "create retrieval key", "description": "Create an organization-owned read-only key scoped to this prompt. Return its full secret only in the initial 201 response and persist only a cryptographic hash; never store the secret in an idempotency receipt. Within the receipt retention period, a retry with the same idempotency key and body creates no duplicate and returns 409 secret_unavailable with the existing key metadata in error.details.key, without a secret. If the original response was lost, explicitly revoke that key and create a replacement using a new idempotency key. Different-body reuse fails idempotency_conflict. No automatic expiry. Rotation creates a new key, then explicitly revokes the old one.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": true, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent promptId; selected organization must be authorized for the current user." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyCreated" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "description": "Structured error, including secret_unavailable when key creation already completed with the same idempotency key and body. error.details.key contains the existing key metadata described by Key, never its secret. The caller must explicitly revoke and replace the key if the initial secret response was lost. Different-body reuse returns idempotency_conflict; existing setup, archive and revision conflicts still apply.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": ["name"], "additionalProperties": false } } } } } }, "/api/v1/organizations/{organizationId}/prompts/{promptId}/keys/{keyId}": { "delete": { "operationId": "revoke_retrieval_key", "summary": "revoke retrieval key", "description": "Explicitly revoke a retrieval key. Subsequent server requests fail authorization, including conditional requests. Already fetched content cannot be recalled.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": true, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent promptId; selected organization must be authorized for the current user." }, { "name": "keyId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent keyId; selected organization must be authorized for the current user." } ], "responses": { "204": { "description": "Completed" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "x-confirmation-required": true } }, "/api/v1/organizations/{organizationId}/warnings": { "get": { "operationId": "list_operational_warnings", "summary": "list operational warnings", "description": "Uses the selected organization and the authenticated user’s current permissions. Applies the same setup and archive rules as the dashboard.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": false, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WarningPage" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/organizations/{organizationId}/warnings/{warningId}/acknowledge": { "post": { "operationId": "acknowledge_warning", "summary": "acknowledge warning", "description": "Record user and acknowledgment point and clear current warning organization-wide. Later qualifying activity reopens it. Archived activity includes 200/304 while archived. Label failures are correlated by prompt, label and key; only success for that same context automatically clears them. No time-based mute.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": false, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "name": "warningId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent warningId; selected organization must be authorized for the current user." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Warning" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revision": { "type": "integer", "minimum": 0 } }, "required": ["revision"], "additionalProperties": false } } } } } }, "/api/v1/organizations/{organizationId}/observability/waitlist": { "get": { "operationId": "get_waitlist_status", "summary": "get waitlist status", "description": "Uses the selected organization and the authenticated user’s current permissions. Applies the same setup and archive rules as the dashboard.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": false, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Waitlist" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "join_observability_waitlist", "summary": "join observability waitlist", "description": "Idempotent one-click organization enrollment. Admin-only write, shared status visible to members. In-app confirmation only; no email, settings form, or active observability access.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": true, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Waitlist" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/organizations/{organizationId}/model-routes": { "get": { "operationId": "list_model_routes", "summary": "list model routes", "description": "Uses the selected organization and the authenticated user’s current permissions. Applies the same setup and archive rules as the dashboard.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": false, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelRoutePage" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/organizations/{organizationId}/provider-connections": { "get": { "operationId": "list_provider_connections", "summary": "list provider connections", "description": "Uses the selected organization and the authenticated user’s current permissions. Applies the same setup and archive rules as the dashboard.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": false, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderConnectionPage" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/organizations/{organizationId}/provider-connections/setup-link": { "post": { "operationId": "get_provider_setup_link", "summary": "get provider setup link", "description": "Return the dashboard destination for secure provider-key entry. Never accept provider secrets through CLI/MCP arguments or return stored secrets.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": true, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardLink" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/organizations/{organizationId}/provider-connections/{connectionId}": { "delete": { "operationId": "remove_provider_connection", "summary": "remove provider connection", "description": "Uses the selected organization and the authenticated user’s current permissions. Applies the same setup and archive rules as the dashboard.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": true, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent connectionId; selected organization must be authorized for the current user." } ], "responses": { "204": { "description": "Completed" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "x-confirmation-required": true } }, "/api/v1/organizations/{organizationId}/billing": { "get": { "operationId": "get_billing", "summary": "get billing", "description": "Uses the selected organization and the authenticated user’s current permissions. Applies the same setup and archive rules as the dashboard.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": false, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Billing" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/organizations/{organizationId}/billing/checkout": { "post": { "operationId": "create_billing_checkout", "summary": "create billing checkout", "description": "Admin starts checkout; payment completes in the browser. Persisted Dodo webhook state is authoritative, never client claims.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": true, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardLink" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "purchase": { "type": "string", "enum": ["pro", "credits"] }, "quantity": { "type": "integer", "minimum": 1 } }, "required": ["purchase"], "additionalProperties": false } } } }, "x-confirmation-required": true } }, "/api/v1/organizations/{organizationId}/billing/cancel-renewal": { "post": { "operationId": "cancel_subscription_renewal", "summary": "cancel subscription renewal", "description": "Require explicit matching organization name and effective period-end date confirmation. Cancellation retains paid access for the remainder of the paid period.", "tags": ["Management"], "security": [ { "ManagementOAuth": ["management"] } ], "x-implementation-status": "implemented", "x-admin-only": true, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Permanent organizationId; selected organization must be authorized for the current user." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Billing" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "organizationName": { "type": "string" }, "periodEnd": { "type": "string", "format": "date-time" } }, "required": ["organizationName", "periodEnd"], "additionalProperties": false } } } }, "x-confirmation-required": true } } }, "components": { "securitySchemes": { "RetrievalKey": { "type": "http", "scheme": "bearer", "bearerFormat": "plr_…", "description": "Organization-owned key scoped to one prompt. Never accepted as management authorization." }, "ManagementOAuth": { "type": "oauth2", "description": "User-based Clerk OAuth. CLI is a public Authorization Code client using S256 PKCE and browser loopback redirect. Hosted MCP uses resource-bound OAuth. Verify issuer, token type, intended audience/resource, scopes, live membership and current role. Do not forward arbitrary OAuth tokens into Convex session JWT auth. OAuth URLs below are placeholders for deployment configuration.", "flows": { "authorizationCode": { "authorizationUrl": "https://clerk.example.com/oauth/authorize", "tokenUrl": "https://clerk.example.com/oauth/token", "scopes": { "management": "Manage the account and organizations within the current user’s permissions." } } } } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": ["code", "message"], "additionalProperties": false } }, "required": ["error"], "additionalProperties": false }, "Message": { "type": "object", "properties": { "role": { "type": "string", "enum": ["system", "user", "assistant"] }, "content": { "type": "string", "maxLength": 100000 } }, "required": ["role", "content"], "additionalProperties": false }, "PromptContent": { "type": "object", "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" }, "minItems": 1, "maxItems": 100 }, "inputType": { "type": "string", "enum": ["user_message", "variables"] }, "modelId": { "type": "string" }, "modelRouteId": { "type": "string" }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 }, "outputSchema": { "type": "string", "description": "JSON-encoded output JSON Schema. No remote reference fetching. Omit to disable structured output." }, "customMetrics": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "required": ["messages", "inputType"], "additionalProperties": false }, "RetrievedPrompt": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "versionId": { "type": "string" }, "version": { "type": "integer", "minimum": 1 }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" }, "minItems": 1, "maxItems": 100 }, "inputType": { "type": "string", "enum": ["user_message", "variables"] }, "modelId": { "type": "string" }, "modelRouteId": { "type": "string" }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 }, "outputSchema": { "type": "string", "description": "JSON-encoded output JSON Schema. No remote reference fetching. Omit to disable structured output." }, "customMetrics": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "required": [ "id", "name", "versionId", "version", "messages", "inputType" ], "additionalProperties": false, "examples": [ { "id": "support-example", "name": "Support assistant", "versionId": "version-example-1", "version": 1, "messages": [ { "role": "system", "content": "Answer questions about the sample product." } ], "inputType": "user_message", "modelRouteId": "openrouter:openai/gpt-4o-mini", "modelId": "gpt-4o-mini" } ] }, "Prompt": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "state": { "type": "string", "enum": ["setup", "ready", "archived"] }, "versionCount": { "type": "integer", "minimum": 0 }, "createdAt": { "type": "string", "format": "date-time" }, "productionVersionId": { "type": ["string", "null"] } }, "required": [ "id", "name", "state", "versionCount", "createdAt", "productionVersionId" ], "additionalProperties": false }, "CreatePrompt": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "content": { "$ref": "#/components/schemas/PromptContent" } }, "required": ["name", "content"], "additionalProperties": false }, "Draft": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/PromptContent" }, "revision": { "type": "integer", "minimum": 0 }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": ["content", "revision", "updatedAt"], "additionalProperties": false }, "DraftWrite": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/PromptContent" }, "revision": { "type": "integer", "minimum": 0 } }, "required": ["content", "revision"], "additionalProperties": false }, "Version": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "integer", "minimum": 1 }, "content": { "$ref": "#/components/schemas/PromptContent" }, "createdAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": "string" } }, "required": ["id", "number", "content", "createdAt", "createdBy"], "additionalProperties": false }, "Label": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$" }, "versionId": { "type": ["string", "null"] }, "revision": { "type": "integer", "minimum": 0 }, "updatedAt": { "type": "string", "format": "date-time" }, "updatedBy": { "type": "string" } }, "required": ["name", "versionId", "revision", "updatedAt", "updatedBy"], "additionalProperties": false }, "LabelMove": { "type": "object", "properties": { "revision": { "type": "integer", "minimum": 0 }, "versionId": { "type": ["string", "null"] }, "acknowledgment": { "type": "string" } }, "required": ["revision", "versionId"], "additionalProperties": false }, "PublicationWarning": { "type": "object", "properties": { "code": { "type": "string", "enum": ["unevaluated", "dataset_changed", "quick_only"] }, "message": { "type": "string" } }, "required": ["code", "message"], "additionalProperties": false }, "Publication": { "type": "object", "properties": { "published": { "type": "boolean" }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/PublicationWarning" } }, "acknowledgment": { "type": ["string", "null"] } }, "required": ["published", "warnings", "acknowledgment"], "additionalProperties": false, "examples": [ { "published": false, "warnings": [ { "code": "unevaluated", "message": "This production version has not been evaluated." } ], "acknowledgment": "opaque-publication-context" } ] }, "DatasetRowInput": { "type": "object", "properties": { "input": { "type": "string", "minLength": 1, "maxLength": 100000 }, "expectedOutput": { "type": "string", "maxLength": 100000 }, "inputFormat": { "type": "string", "enum": ["text", "json"], "description": "Field format. Omitted fields use text for new cases; edits preserve the existing format. JSON content is stored as a JSON-encoded string." }, "referenceFormat": { "type": "string", "enum": ["text", "json"], "description": "Field format. Omitted fields use text for new cases; edits preserve the existing format. JSON content is stored as a JSON-encoded string." } }, "required": ["input"], "additionalProperties": false }, "DatasetRow": { "type": "object", "properties": { "id": { "type": "string" }, "position": { "type": "integer", "minimum": 0 }, "input": { "type": "string", "minLength": 1, "maxLength": 100000 }, "expectedOutput": { "type": "string", "maxLength": 100000 }, "inputFormat": { "type": "string", "enum": ["text", "json"], "description": "Field format. Omitted fields use text for new cases; edits preserve the existing format. JSON content is stored as a JSON-encoded string." }, "referenceFormat": { "type": "string", "enum": ["text", "json"], "description": "Field format. Omitted fields use text for new cases; edits preserve the existing format. JSON content is stored as a JSON-encoded string." } }, "required": ["id", "position", "input"], "additionalProperties": false }, "Dataset": { "type": "object", "properties": { "id": { "type": "string" }, "revision": { "type": "integer", "minimum": 0 }, "count": { "type": "integer", "minimum": 0 }, "capacity": { "type": "integer", "enum": [10, 500] }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/DatasetRow" } } }, "required": ["id", "revision", "count", "capacity", "rows"], "additionalProperties": false }, "DatasetImport": { "type": "object", "properties": { "rows": { "type": "array", "items": { "$ref": "#/components/schemas/DatasetRowInput" }, "maxItems": 1000 }, "mode": { "type": "string", "enum": ["append", "replace"], "default": "append" }, "revision": { "type": "integer", "minimum": 0 } }, "required": ["rows", "revision"], "additionalProperties": false, "examples": [ { "revision": 0, "mode": "append", "rows": [ { "input": "Hello", "expectedOutput": "Hi" } ] } ] }, "ImportResult": { "type": "object", "properties": { "added": { "type": "integer", "minimum": 0 }, "skipped": { "type": "integer", "minimum": 0 }, "count": { "type": "integer", "minimum": 0 }, "revision": { "type": "integer", "minimum": 0 }, "skippedRows": { "type": "array", "items": { "$ref": "#/components/schemas/SkippedImportRow" } } }, "required": ["added", "skipped", "count", "revision", "skippedRows"], "additionalProperties": false }, "EvaluationStart": { "type": "object", "properties": { "versionId": { "type": "string" }, "scope": { "type": "string", "enum": ["quick", "comprehensive"], "default": "quick" }, "scoringMethod": { "type": "string", "enum": ["expected", "human_review", "llm_judge"] }, "comparison": { "type": "string", "enum": ["reuse_production", "rerun_both"], "default": "reuse_production" } }, "required": ["versionId", "scoringMethod"], "additionalProperties": false }, "SetupStart": { "type": "object", "properties": { "draftRevision": { "type": "integer", "minimum": 0 }, "scope": { "type": "string", "enum": ["quick", "comprehensive"], "default": "quick" }, "scoringMethod": { "type": "string", "enum": ["expected", "human_review", "llm_judge"] } }, "required": ["draftRevision", "scoringMethod"], "additionalProperties": false }, "Evaluation": { "type": "object", "properties": { "id": { "type": "string" }, "promptId": { "type": "string" }, "versionId": { "type": "string" }, "version": { "type": "integer", "minimum": 0 }, "status": { "type": "string", "enum": [ "pending", "running", "paused", "completed", "failed", "cancelled" ] }, "scope": { "type": "string", "enum": ["quick", "comprehensive"] }, "totalCases": { "type": "integer", "minimum": 0 }, "datasetSize": { "type": "integer", "minimum": 0 }, "scoredCases": { "type": "integer", "minimum": 0 }, "pendingReviewCases": { "type": "integer", "minimum": 0 }, "passedCases": { "type": "integer", "minimum": 0 }, "failedCases": { "type": "integer", "minimum": 0 }, "passRate": { "type": "number", "minimum": 0, "maximum": 100 }, "productionRunId": { "type": ["string", "null"] }, "createdAt": { "type": "string", "format": "date-time" }, "error": { "type": ["string", "null"] } }, "required": [ "id", "promptId", "versionId", "version", "status", "scope", "totalCases", "datasetSize", "scoredCases", "pendingReviewCases", "passedCases", "failedCases", "passRate", "productionRunId", "createdAt", "error" ], "additionalProperties": false }, "ComparisonStart": { "type": "object", "properties": { "candidateRunId": { "type": "string" }, "productionRunId": { "type": "string" }, "productionReused": { "type": "boolean" } }, "required": ["candidateRunId", "productionRunId", "productionReused"], "additionalProperties": false }, "EvaluationResult": { "type": "object", "properties": { "id": { "type": "string" }, "position": { "type": "integer", "minimum": 0 }, "input": { "type": "string" }, "expectedOutput": { "type": ["string", "null"] }, "actualOutput": { "type": ["string", "null"] }, "outcome": { "type": "string", "enum": ["passed", "failed", "unscored", "errored"] }, "reason": { "type": ["string", "null"] }, "reviewedBy": { "type": ["string", "null"] }, "reviewedByClientId": { "type": ["string", "null"] } }, "required": [ "id", "position", "input", "expectedOutput", "actualOutput", "outcome", "reason", "reviewedBy", "reviewedByClientId" ], "additionalProperties": false }, "Review": { "type": "object", "properties": { "resultId": { "type": "string" }, "decision": { "type": "string", "enum": ["accept_generated", "edit_expected", "reject_generated"] }, "expectedOutput": { "type": "string" } }, "required": ["resultId", "decision"], "additionalProperties": false }, "Coverage": { "type": "object", "properties": { "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/PublicationWarning" } }, "datasetSize": { "type": "integer", "minimum": 0 }, "lastEvaluatedSize": { "type": ["integer", "null"] }, "evaluationId": { "type": ["string", "null"] } }, "required": [ "warnings", "datasetSize", "lastEvaluatedSize", "evaluationId" ], "additionalProperties": false }, "Key": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "lastUsedAt": { "type": ["string", "null"], "format": "date-time" }, "revokedAt": { "type": ["string", "null"], "format": "date-time" } }, "required": [ "id", "name", "prefix", "createdAt", "lastUsedAt", "revokedAt" ], "additionalProperties": false }, "KeyCreated": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/Key" }, "secret": { "type": "string", "writeOnly": false, "description": "Returned only at creation. Store securely; never include in logs." } }, "required": ["key", "secret"], "additionalProperties": false }, "Warning": { "type": "object", "properties": { "id": { "type": "string" }, "promptId": { "type": "string" }, "keyId": { "type": ["string", "null"] }, "label": { "type": ["string", "null"] }, "code": { "type": "string", "enum": ["archived_in_use", "label_not_found", "label_unassigned"] }, "active": { "type": "boolean" }, "revision": { "type": "integer", "minimum": 0 }, "lastSeenAt": { "type": "string", "format": "date-time" }, "acknowledgedBy": { "type": ["string", "null"] }, "acknowledgedAt": { "type": ["string", "null"], "format": "date-time" } }, "required": [ "id", "promptId", "keyId", "label", "code", "active", "revision", "lastSeenAt", "acknowledgedBy", "acknowledgedAt" ], "additionalProperties": false }, "Waitlist": { "type": "object", "properties": { "enrolled": { "type": "boolean" }, "canEnroll": { "type": "boolean" }, "joinedAt": { "type": ["string", "null"], "format": "date-time" }, "joinedBy": { "type": ["string", "null"] } }, "required": ["enrolled", "canEnroll", "joinedAt", "joinedBy"], "additionalProperties": false }, "Organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" }, "plan": { "type": "string", "enum": ["free", "pro"] }, "paused": { "type": "boolean" } }, "required": ["id", "name", "role", "plan", "paused"], "additionalProperties": false }, "Member": { "type": "object", "properties": { "userId": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string", "enum": ["admin", "member"] } }, "required": ["userId", "name", "role"], "additionalProperties": false }, "Invitation": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string", "format": "email" }, "role": { "type": "string", "enum": ["admin", "member"] }, "status": { "type": "string", "enum": ["pending", "accepted", "revoked"] } }, "required": ["id", "email", "role", "status"], "additionalProperties": false }, "DashboardLink": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "reason": { "type": "string" } }, "required": ["url", "reason"], "additionalProperties": false }, "Billing": { "type": "object", "properties": { "plan": { "type": "string", "enum": ["free", "pro"] }, "renewsAt": { "type": ["string", "null"], "format": "date-time" }, "cancelAtPeriodEnd": { "type": "boolean" }, "creditsRemaining": { "type": "number", "minimum": 0 } }, "required": [ "plan", "renewsAt", "cancelAtPeriodEnd", "creditsRemaining" ], "additionalProperties": false }, "ProviderConnection": { "type": "object", "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "connected": { "type": "boolean" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": ["id", "provider", "connected", "updatedAt"], "additionalProperties": false }, "ModelRoute": { "type": "object", "properties": { "id": { "type": "string" }, "modelId": { "type": "string" }, "providerId": { "type": "string" }, "displayName": { "type": "string" }, "supportsTemperature": { "type": "boolean" } }, "required": [ "id", "modelId", "providerId", "displayName", "supportsTemperature" ], "additionalProperties": false }, "Profile": { "type": "object", "properties": { "userId": { "type": "string" }, "defaultOrganizationId": { "type": ["string", "null"] } }, "required": ["userId", "defaultOrganizationId"], "additionalProperties": false }, "OrganizationPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Organization" } }, "nextCursor": { "type": ["string", "null"] } }, "required": ["items", "nextCursor"], "additionalProperties": false }, "MemberPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Member" } }, "nextCursor": { "type": ["string", "null"] } }, "required": ["items", "nextCursor"], "additionalProperties": false }, "InvitationPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Invitation" } }, "nextCursor": { "type": ["string", "null"] } }, "required": ["items", "nextCursor"], "additionalProperties": false }, "PromptPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Prompt" } }, "nextCursor": { "type": ["string", "null"] } }, "required": ["items", "nextCursor"], "additionalProperties": false }, "VersionPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Version" } }, "nextCursor": { "type": ["string", "null"] } }, "required": ["items", "nextCursor"], "additionalProperties": false }, "LabelPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Label" } }, "nextCursor": { "type": ["string", "null"] } }, "required": ["items", "nextCursor"], "additionalProperties": false }, "EvaluationPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Evaluation" } }, "nextCursor": { "type": ["string", "null"] } }, "required": ["items", "nextCursor"], "additionalProperties": false }, "EvaluationResultPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/EvaluationResult" } }, "nextCursor": { "type": ["string", "null"] } }, "required": ["items", "nextCursor"], "additionalProperties": false }, "KeyPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Key" } }, "nextCursor": { "type": ["string", "null"] } }, "required": ["items", "nextCursor"], "additionalProperties": false }, "WarningPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Warning" } }, "nextCursor": { "type": ["string", "null"] } }, "required": ["items", "nextCursor"], "additionalProperties": false }, "ModelRoutePage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ModelRoute" } }, "nextCursor": { "type": ["string", "null"] } }, "required": ["items", "nextCursor"], "additionalProperties": false }, "ProviderConnectionPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderConnection" } }, "nextCursor": { "type": ["string", "null"] } }, "required": ["items", "nextCursor"], "additionalProperties": false }, "SkippedImportRow": { "type": "object", "properties": { "row": { "type": "integer", "minimum": 1, "description": "One-based row number in the submitted import." }, "reason": { "type": "string", "enum": ["duplicate"] } }, "required": ["row", "reason"], "additionalProperties": false } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Management writes: scoped to OAuth user+client+organization+operation. Store request digest and response for at least 24 hours. Same key/body replays original response, including after completion; different body fails idempotency_conflict. Exception: create_retrieval_key stores a non-secret receipt referencing the created key, never its secret. Same-key/body retries return 409 secret_unavailable with existing key metadata and do not create another key. Evaluation creation must not execute twice." } }, "responses": { "Error": { "description": "Structured error. 409 for stale revisions, setup/archival gates, unassigned labels or idempotency conflict. 422 for invalid rows/capacity; 429 includes Retry-After; transient 503 is retryable with the original idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "x-management-release-gates": [ "Live Clerk OAuth issuer/resource/audience and lifecycle conformance", "Trusted Convex authorization adapter using current user and selected organization", "Runtime conformance for all contract-only operations", "Idempotency receipts and pagination implementation" ] }