{ "openapi": "3.1.0", "info": { "title": "Promptic API", "version": "1.0.0", "description": "API for managing AI components, experiments, traces, and evaluations." }, "servers": [ { "url": "/api/v1", "description": "Current origin" }, { "url": "https://promptic.eu/api/v1", "description": "Production" }, { "url": "http://localhost:3000/api/v1", "description": "Local development" } ], "components": { "securitySchemes": { "BearerApiKey": { "type": "http", "scheme": "bearer", "description": "API key from workspace settings" } } }, "paths": { "/workspace": { "get": { "tags": ["Workspace"], "summary": "Get current workspace", "security": [ { "BearerApiKey": [] } ], "responses": { "200": { "description": "Workspace details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": ["id", "name", "description", "createdAt", "updatedAt"], "additionalProperties": false } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } } }, "/workspaces": { "get": { "tags": ["Workspace"], "summary": "List workspaces for current user", "description": "Requires session authentication (not API key)", "responses": { "200": { "description": "List of workspaces", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": ["id", "name", "description", "createdAt", "updatedAt"], "additionalProperties": false } } }, "required": ["data"], "additionalProperties": false } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } } }, "/components": { "get": { "tags": ["Components"], "summary": "List all components", "security": [ { "BearerApiKey": [] } ], "responses": { "200": { "description": "List of components", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "workspaceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "description", "workspaceId", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "required": ["data"], "additionalProperties": false } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } }, "post": { "tags": ["Components"], "summary": "Create a component", "security": [ { "BearerApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["name"], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": ["id"], "additionalProperties": false } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } } }, "/components/{componentId}": { "get": { "tags": ["Components"], "summary": "Get a component by ID", "security": [ { "BearerApiKey": [] } ], "parameters": [ { "in": "path", "name": "componentId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Component details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "workspaceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "description", "workspaceId", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } }, "delete": { "tags": ["Components"], "summary": "Delete a component", "security": [ { "BearerApiKey": [] } ], "parameters": [ { "in": "path", "name": "componentId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Deleted" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } } }, "/components/{componentId}/datasets": { "get": { "tags": ["Datasets"], "summary": "List datasets for a component", "security": [ { "BearerApiKey": [] } ], "parameters": [ { "in": "path", "name": "componentId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "List of datasets", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiComponentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "itemCount": { "type": "number" }, "createdAt": { "type": "string" } }, "required": [ "id", "name", "description", "aiComponentId", "itemCount", "createdAt" ], "additionalProperties": false } } }, "required": ["data"], "additionalProperties": false } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } }, "post": { "tags": ["Datasets"], "summary": "Create a dataset", "security": [ { "BearerApiKey": [] } ], "parameters": [ { "in": "path", "name": "componentId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "traceIds": { "type": "array", "items": { "type": "string" } } }, "required": ["name"], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiComponentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "itemCount": { "type": "number" }, "createdAt": { "type": "string" } }, "required": [ "id", "name", "description", "aiComponentId", "itemCount", "createdAt" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } } }, "/components/{componentId}/datasets/{datasetId}": { "get": { "tags": ["Datasets"], "summary": "Get a dataset with items", "security": [ { "BearerApiKey": [] } ], "parameters": [ { "in": "path", "name": "componentId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "datasetId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Dataset with items", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiComponentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "itemCount": { "type": "number" }, "createdAt": { "type": "string" } }, "required": [ "id", "name", "description", "aiComponentId", "itemCount", "createdAt" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } }, "delete": { "tags": ["Datasets"], "summary": "Delete a dataset", "security": [ { "BearerApiKey": [] } ], "parameters": [ { "in": "path", "name": "componentId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "datasetId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Deleted" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } } }, "/components/{componentId}/datasets/{datasetId}/annotations": { "get": { "tags": ["Annotations"], "summary": "List annotations for a dataset", "security": [ { "BearerApiKey": [] } ], "parameters": [ { "in": "path", "name": "componentId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "datasetId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "List of annotations", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "traceDbId": { "type": "string" }, "userId": { "type": "string" }, "rating": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "comment": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" } }, "required": ["id", "traceDbId", "userId", "rating", "comment", "createdAt"], "additionalProperties": false } } }, "required": ["data"], "additionalProperties": false } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } } }, "/components/{componentId}/runs": { "get": { "tags": ["Runs"], "summary": "List runs for a component", "security": [ { "BearerApiKey": [] } ], "parameters": [ { "in": "path", "name": "componentId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "List of runs", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "datasetId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "aiComponentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "traceCount": { "type": "number" }, "createdAt": { "type": "string" } }, "required": [ "id", "name", "datasetId", "aiComponentId", "traceCount", "createdAt" ], "additionalProperties": false } } }, "required": ["data"], "additionalProperties": false } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } }, "post": { "tags": ["Runs"], "summary": "Create a run", "security": [ { "BearerApiKey": [] } ], "parameters": [ { "in": "path", "name": "componentId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "datasetId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "traceIds": { "type": "array", "items": { "type": "string" } } }, "required": ["datasetId"], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "datasetId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "aiComponentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "traceCount": { "type": "number" }, "createdAt": { "type": "string" } }, "required": [ "id", "name", "datasetId", "aiComponentId", "traceCount", "createdAt" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } } }, "/components/{componentId}/runs/{runId}": { "get": { "tags": ["Runs"], "summary": "Get a run with traces", "security": [ { "BearerApiKey": [] } ], "parameters": [ { "in": "path", "name": "componentId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "runId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Run with traces", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "datasetId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "aiComponentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "traceCount": { "type": "number" }, "createdAt": { "type": "string" } }, "required": [ "id", "name", "datasetId", "aiComponentId", "traceCount", "createdAt" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } }, "delete": { "tags": ["Runs"], "summary": "Delete a run", "security": [ { "BearerApiKey": [] } ], "parameters": [ { "in": "path", "name": "componentId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "runId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Deleted" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } } }, "/components/{componentId}/runs/{runId}/annotations": { "get": { "tags": ["Annotations"], "summary": "List annotations for a run", "security": [ { "BearerApiKey": [] } ], "parameters": [ { "in": "path", "name": "componentId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "runId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "List of annotations", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "traceDbId": { "type": "string" }, "userId": { "type": "string" }, "rating": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "comment": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" } }, "required": ["id", "traceDbId", "userId", "rating", "comment", "createdAt"], "additionalProperties": false } } }, "required": ["data"], "additionalProperties": false } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } }, "post": { "tags": ["Annotations"], "summary": "Create or update an annotation", "security": [ { "BearerApiKey": [] } ], "parameters": [ { "in": "path", "name": "componentId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "runId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "traceDbId": { "type": "string", "minLength": 1 }, "rating": { "type": "string" }, "comment": { "type": "string" } }, "required": ["traceDbId"], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "traceDbId": { "type": "string" }, "userId": { "type": "string" }, "rating": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "comment": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" } }, "required": ["id", "traceDbId", "userId", "rating", "comment", "createdAt"], "additionalProperties": false } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } } }, "/components/{componentId}/runs/{runId}/annotations/{annotationId}": { "delete": { "tags": ["Annotations"], "summary": "Delete an annotation", "security": [ { "BearerApiKey": [] } ], "parameters": [ { "in": "path", "name": "componentId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "runId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "annotationId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Deleted" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } } }, "/components/{componentId}/evaluations": { "get": { "tags": ["Evaluations"], "summary": "List evaluations for a component", "security": [ { "BearerApiKey": [] } ], "parameters": [ { "in": "path", "name": "componentId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "List of evaluations", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "datasetId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string" } }, "required": ["id", "name", "status", "datasetId", "createdAt"], "additionalProperties": false } } }, "required": ["data"], "additionalProperties": false } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } }, "post": { "tags": ["Evaluations"], "summary": "Create an evaluation", "security": [ { "BearerApiKey": [] } ], "parameters": [ { "in": "path", "name": "componentId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "datasetId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "config": { "type": "object", "properties": {}, "additionalProperties": {} } }, "required": ["datasetId"], "additionalProperties": false } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" } }, "required": ["id", "name", "status"], "additionalProperties": false } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } } }, "/components/{componentId}/evaluations/{evaluationId}": { "get": { "tags": ["Evaluations"], "summary": "Get an evaluation by ID", "security": [ { "BearerApiKey": [] } ], "parameters": [ { "in": "path", "name": "componentId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "evaluationId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Evaluation details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "datasetId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": ["id", "name", "status", "datasetId"], "additionalProperties": false } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } } }, "/components/{componentId}/deployment": { "get": { "tags": ["Deployment"], "summary": "Get current deployment for a component", "security": [ { "BearerApiKey": [] } ], "parameters": [ { "in": "path", "name": "componentId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deployment details", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "aiComponentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "experimentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "experiment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "targetModel": { "type": "string" }, "provider": { "type": "string" }, "aiComponentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "taskType": { "type": "string" }, "optimizer": { "type": "string" }, "experimentStatus": { "type": "string" }, "promptFormat": { "type": "string" }, "initialPromptMessages": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "content": { "type": "string" } }, "required": ["role", "content"], "additionalProperties": false } }, "inputVariables": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "column": { "type": "string" } }, "required": ["name", "column"], "additionalProperties": false } }, { "type": "null" } ] }, "hyperparameters": { "anyOf": [ { "type": "object", "properties": { "epochs": { "type": "number" }, "numFewShots": { "type": "number" }, "trainSplitRatio": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": ["epochs", "numFewShots"], "additionalProperties": false }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "description", "targetModel", "provider", "aiComponentId", "taskType", "optimizer", "experimentStatus", "promptFormat", "initialPromptMessages", "hyperparameters", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": ["aiComponentId", "experimentId", "experiment"], "additionalProperties": false }, { "type": "null" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } }, "post": { "tags": ["Deployment"], "summary": "Deploy an experiment to a component", "security": [ { "BearerApiKey": [] } ], "parameters": [ { "in": "path", "name": "componentId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "experimentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": ["experimentId"], "additionalProperties": false } } } }, "responses": { "201": { "description": "Deployed", "content": { "application/json": { "schema": { "type": "object", "properties": { "aiComponentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "experimentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": ["aiComponentId", "experimentId"], "additionalProperties": false } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } }, "delete": { "tags": ["Deployment"], "summary": "Undeploy from a component", "security": [ { "BearerApiKey": [] } ], "parameters": [ { "in": "path", "name": "componentId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Undeployed" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } } }, "/components/{componentId}/deployment/prompt": { "get": { "tags": ["Deployment"], "summary": "Get the deployed prompt for a component", "security": [ { "BearerApiKey": [] } ], "parameters": [ { "in": "path", "name": "componentId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deployed prompt details", "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "promptMessages": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "content": { "type": "string" } }, "required": ["role", "content"], "additionalProperties": false } }, "promptFormat": { "type": "string" }, "model": { "type": "string" }, "provider": { "type": "string" }, "componentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "componentName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "experimentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "iterationId": { "type": "number" }, "score": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "schemaSnapshot": { "anyOf": [ {}, { "type": "null" } ] } }, "required": [ "prompt", "promptMessages", "promptFormat", "model", "provider", "componentId", "componentName", "experimentId", "iterationId", "score", "schemaSnapshot" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } }, "404": { "description": "No deployment found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } } }, "/experiments": { "get": { "tags": ["Experiments"], "summary": "List experiments", "security": [ { "BearerApiKey": [] } ], "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 50 } }, { "in": "query", "name": "offset", "schema": { "type": "integer", "default": 0 } }, { "in": "query", "name": "component_id", "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "status", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of experiments", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "targetModel": { "type": "string" }, "provider": { "type": "string" }, "aiComponentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "taskType": { "type": "string" }, "optimizer": { "type": "string" }, "experimentStatus": { "type": "string" }, "promptFormat": { "type": "string" }, "initialPromptMessages": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "content": { "type": "string" } }, "required": ["role", "content"], "additionalProperties": false } }, "inputVariables": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "column": { "type": "string" } }, "required": ["name", "column"], "additionalProperties": false } }, { "type": "null" } ] }, "hyperparameters": { "anyOf": [ { "type": "object", "properties": { "epochs": { "type": "number" }, "numFewShots": { "type": "number" }, "trainSplitRatio": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": ["epochs", "numFewShots"], "additionalProperties": false }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "description", "targetModel", "provider", "aiComponentId", "taskType", "optimizer", "experimentStatus", "promptFormat", "initialPromptMessages", "hyperparameters", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "required": ["data"], "additionalProperties": false } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } }, "post": { "tags": ["Experiments"], "summary": "Create an experiment", "security": [ { "BearerApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "aiComponentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "targetModel": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "provider": { "default": "openai", "type": "string" }, "customProviderId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "taskType": { "default": "classification", "type": "string" }, "optimizer": { "default": "prompticV2", "type": "string" }, "promptFormat": { "default": "single", "type": "string" }, "initialPrompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "initialPromptMessages": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "content": { "type": "string" } }, "required": ["role", "content"], "additionalProperties": false } }, "initialPredictionModelSchema": {}, "hyperparameters": { "default": { "epochs": 3, "numFewShots": 8 }, "type": "object", "properties": { "epochs": { "type": "number" }, "numFewShots": { "type": "number" }, "trainSplitRatio": { "anyOf": [ { "type": "number", "minimum": 0.1, "maximum": 0.95 }, { "type": "null" } ] } }, "required": ["epochs", "numFewShots"], "additionalProperties": {} }, "runNumber": { "type": "number" } }, "required": [ "aiComponentId", "targetModel", "provider", "taskType", "optimizer", "promptFormat", "hyperparameters" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "targetModel": { "type": "string" }, "provider": { "type": "string" }, "aiComponentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "taskType": { "type": "string" }, "optimizer": { "type": "string" }, "experimentStatus": { "type": "string" }, "promptFormat": { "type": "string" }, "initialPromptMessages": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "content": { "type": "string" } }, "required": ["role", "content"], "additionalProperties": false } }, "inputVariables": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "column": { "type": "string" } }, "required": ["name", "column"], "additionalProperties": false } }, { "type": "null" } ] }, "hyperparameters": { "anyOf": [ { "type": "object", "properties": { "epochs": { "type": "number" }, "numFewShots": { "type": "number" }, "trainSplitRatio": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": ["epochs", "numFewShots"], "additionalProperties": false }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "description", "targetModel", "provider", "aiComponentId", "taskType", "optimizer", "experimentStatus", "promptFormat", "initialPromptMessages", "hyperparameters", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } } }, "/experiments/{experimentId}": { "get": { "tags": ["Experiments"], "summary": "Get an experiment by ID", "security": [ { "BearerApiKey": [] } ], "parameters": [ { "in": "path", "name": "experimentId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Experiment details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "targetModel": { "type": "string" }, "provider": { "type": "string" }, "aiComponentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "taskType": { "type": "string" }, "optimizer": { "type": "string" }, "experimentStatus": { "type": "string" }, "promptFormat": { "type": "string" }, "initialPromptMessages": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "content": { "type": "string" } }, "required": ["role", "content"], "additionalProperties": false } }, "inputVariables": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "column": { "type": "string" } }, "required": ["name", "column"], "additionalProperties": false } }, { "type": "null" } ] }, "hyperparameters": { "anyOf": [ { "type": "object", "properties": { "epochs": { "type": "number" }, "numFewShots": { "type": "number" }, "trainSplitRatio": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": ["epochs", "numFewShots"], "additionalProperties": false }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "description", "targetModel", "provider", "aiComponentId", "taskType", "optimizer", "experimentStatus", "promptFormat", "initialPromptMessages", "hyperparameters", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } }, "patch": { "tags": ["Experiments"], "summary": "Update a pending experiment", "security": [ { "BearerApiKey": [] } ], "parameters": [ { "in": "path", "name": "experimentId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "targetModel": { "type": "string" }, "provider": { "type": "string" }, "taskType": { "type": "string" }, "optimizer": { "type": "string" }, "promptFormat": { "type": "string" }, "initialPrompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "initialPromptMessages": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "content": { "type": "string" } }, "required": ["role", "content"], "additionalProperties": false } }, "initialPredictionModelSchema": {}, "hyperparameters": { "type": "object", "properties": { "epochs": { "type": "number" }, "numFewShots": { "type": "number" }, "trainSplitRatio": { "anyOf": [ { "type": "number", "minimum": 0.1, "maximum": 0.95 }, { "type": "null" } ] } }, "required": ["epochs", "numFewShots"], "additionalProperties": {} } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "targetModel": { "type": "string" }, "provider": { "type": "string" }, "aiComponentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "taskType": { "type": "string" }, "optimizer": { "type": "string" }, "experimentStatus": { "type": "string" }, "promptFormat": { "type": "string" }, "initialPromptMessages": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "content": { "type": "string" } }, "required": ["role", "content"], "additionalProperties": false } }, "inputVariables": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "column": { "type": "string" } }, "required": ["name", "column"], "additionalProperties": false } }, { "type": "null" } ] }, "hyperparameters": { "anyOf": [ { "type": "object", "properties": { "epochs": { "type": "number" }, "numFewShots": { "type": "number" }, "trainSplitRatio": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": ["epochs", "numFewShots"], "additionalProperties": false }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "description", "targetModel", "provider", "aiComponentId", "taskType", "optimizer", "experimentStatus", "promptFormat", "initialPromptMessages", "hyperparameters", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } }, "409": { "description": "Not in pending state", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } }, "delete": { "tags": ["Experiments"], "summary": "Delete an experiment", "security": [ { "BearerApiKey": [] } ], "parameters": [ { "in": "path", "name": "experimentId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Deleted" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } } }, "/experiments/{experimentId}/start": { "post": { "tags": ["Experiments"], "summary": "Start a pending experiment", "security": [ { "BearerApiKey": [] } ], "parameters": [ { "in": "path", "name": "experimentId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Experiment scheduled", "content": { "application/json": { "schema": { "type": "object", "properties": { "messageId": { "type": "string" }, "status": { "type": "string" } }, "required": ["messageId", "status"], "additionalProperties": false } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } }, "409": { "description": "Not in pending state", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } } }, "/experiments/{experimentId}/duplicate": { "post": { "tags": ["Experiments"], "summary": "Duplicate an experiment (clones observations + evaluators)", "description": "Creates a new experiment under the same AI component as the source, copying observations and evaluators. The initial prompt comes from the source experiment by default; pass `continueFromOptimized: true` to seed from the source's best optimized prompt (continue flow), or `initialPromptOverride` to override with custom text.", "security": [ { "BearerApiKey": [] } ], "parameters": [ { "in": "path", "name": "experimentId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "continueFromOptimized": { "type": "boolean" }, "initialPromptOverride": { "type": "string" } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "New experiment created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "targetModel": { "type": "string" }, "provider": { "type": "string" }, "aiComponentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "taskType": { "type": "string" }, "optimizer": { "type": "string" }, "experimentStatus": { "type": "string" }, "promptFormat": { "type": "string" }, "initialPromptMessages": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "content": { "type": "string" } }, "required": ["role", "content"], "additionalProperties": false } }, "inputVariables": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "column": { "type": "string" } }, "required": ["name", "column"], "additionalProperties": false } }, { "type": "null" } ] }, "hyperparameters": { "anyOf": [ { "type": "object", "properties": { "epochs": { "type": "number" }, "numFewShots": { "type": "number" }, "trainSplitRatio": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": ["epochs", "numFewShots"], "additionalProperties": false }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "modelUnavailable": { "type": "boolean" } }, "required": [ "id", "name", "description", "targetModel", "provider", "aiComponentId", "taskType", "optimizer", "experimentStatus", "promptFormat", "initialPromptMessages", "hyperparameters", "createdAt", "updatedAt", "modelUnavailable" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } }, "404": { "description": "Source experiment not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } } }, "/experiments/{experimentId}/evaluators": { "get": { "tags": ["Evaluators"], "summary": "List evaluators for an experiment", "security": [ { "BearerApiKey": [] } ], "parameters": [ { "in": "path", "name": "experimentId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "List of evaluators", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "experimentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "type": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scaleMin": { "type": "number" }, "scaleMax": { "type": "number" }, "weight": { "type": "number" }, "createdAt": { "type": "string" } }, "required": [ "id", "experimentId", "name", "type", "description", "scaleMin", "scaleMax", "weight", "createdAt" ], "additionalProperties": false } } }, "required": ["data"], "additionalProperties": false } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } }, "post": { "tags": ["Evaluators"], "summary": "Create evaluator(s)", "description": "Accepts a single evaluator object or an array", "security": [ { "BearerApiKey": [] } ], "parameters": [ { "in": "path", "name": "experimentId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scaleMin": { "default": 0, "type": "number" }, "scaleMax": { "default": 1, "type": "number" }, "weight": { "default": 1, "type": "number" }, "config": {} }, "required": ["name", "type", "scaleMin", "scaleMax", "weight"], "additionalProperties": false }, { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scaleMin": { "default": 0, "type": "number" }, "scaleMax": { "default": 1, "type": "number" }, "weight": { "default": 1, "type": "number" }, "config": {} }, "required": ["name", "type", "scaleMin", "scaleMax", "weight"], "additionalProperties": false } } ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "experimentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "type": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scaleMin": { "type": "number" }, "scaleMax": { "type": "number" }, "weight": { "type": "number" }, "createdAt": { "type": "string" } }, "required": [ "id", "experimentId", "name", "type", "description", "scaleMin", "scaleMax", "weight", "createdAt" ], "additionalProperties": false } } }, "required": ["data"], "additionalProperties": false } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } } }, "/experiments/{experimentId}/evaluators/{evaluatorId}": { "patch": { "tags": ["Evaluators"], "summary": "Update an evaluator", "security": [ { "BearerApiKey": [] } ], "parameters": [ { "in": "path", "name": "experimentId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "evaluatorId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "type": "string" }, "scaleMin": { "type": "number" }, "scaleMax": { "type": "number" }, "weight": { "type": "number" }, "config": {} }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "experimentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "type": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scaleMin": { "type": "number" }, "scaleMax": { "type": "number" }, "weight": { "type": "number" }, "createdAt": { "type": "string" } }, "required": [ "id", "experimentId", "name", "type", "description", "scaleMin", "scaleMax", "weight", "createdAt" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } }, "delete": { "tags": ["Evaluators"], "summary": "Delete an evaluator", "security": [ { "BearerApiKey": [] } ], "parameters": [ { "in": "path", "name": "experimentId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "evaluatorId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Deleted" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } } }, "/experiments/{experimentId}/observations": { "get": { "tags": ["Observations"], "summary": "List observations for an experiment", "security": [ { "BearerApiKey": [] } ], "parameters": [ { "in": "path", "name": "experimentId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "List of observations", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "experimentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "idx": { "type": "number" }, "expected": { "type": "string" }, "variables": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "split": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "experimentId", "idx", "expected", "variables", "split", "createdAt" ], "additionalProperties": false } } }, "required": ["data"], "additionalProperties": false } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } }, "post": { "tags": ["Observations"], "summary": "Create observation(s)", "description": "Accepts a single observation object or an array (max 1000)", "security": [ { "BearerApiKey": [] } ], "parameters": [ { "in": "path", "name": "experimentId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "expected": { "type": "string", "minLength": 1 }, "idx": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "variables": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "split": { "default": "eval", "type": "string" } }, "required": ["expected", "variables", "split"], "additionalProperties": false }, { "type": "array", "items": { "type": "object", "properties": { "expected": { "type": "string", "minLength": 1 }, "idx": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "variables": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "split": { "default": "eval", "type": "string" } }, "required": ["expected", "variables", "split"], "additionalProperties": false } } ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "experimentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "idx": { "type": "number" }, "expected": { "type": "string" }, "variables": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "split": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "experimentId", "idx", "expected", "variables", "split", "createdAt" ], "additionalProperties": false } } }, "required": ["data"], "additionalProperties": false } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } } }, "/experiments/{experimentId}/observations/{observationId}": { "patch": { "tags": ["Observations"], "summary": "Update an observation", "security": [ { "BearerApiKey": [] } ], "parameters": [ { "in": "path", "name": "experimentId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "observationId", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expected": { "type": "string" }, "variables": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "split": { "type": "string" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number" }, "experimentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "idx": { "type": "number" }, "expected": { "type": "string" }, "variables": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "split": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "experimentId", "idx", "expected", "variables", "split", "createdAt" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } }, "delete": { "tags": ["Observations"], "summary": "Delete an observation", "security": [ { "BearerApiKey": [] } ], "parameters": [ { "in": "path", "name": "experimentId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "observationId", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Deleted" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } } }, "/experiments/{experimentId}/iterations": { "get": { "tags": ["Iterations"], "summary": "List iterations for an experiment", "security": [ { "BearerApiKey": [] } ], "parameters": [ { "in": "path", "name": "experimentId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "List of iterations", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "experimentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "iteration": { "type": "number" }, "prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "overallNormalizedScore": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "evalNormalizedScore": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "createdAt": { "type": "string" } }, "required": [ "id", "experimentId", "iteration", "prompt", "overallNormalizedScore", "createdAt" ], "additionalProperties": false } } }, "required": ["data"], "additionalProperties": false } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } } }, "/experiments/{experimentId}/iterations/best": { "get": { "tags": ["Iterations"], "summary": "Get the best iteration for an experiment", "security": [ { "BearerApiKey": [] } ], "parameters": [ { "in": "path", "name": "experimentId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Best iteration with scores", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number" }, "experimentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "iteration": { "type": "number" }, "prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "overallNormalizedScore": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "evalNormalizedScore": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "createdAt": { "type": "string" } }, "required": [ "id", "experimentId", "iteration", "prompt", "overallNormalizedScore", "createdAt" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } }, "404": { "description": "No iterations found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } } }, "/experiments/{experimentId}/iterations/{iterationId}": { "get": { "tags": ["Iterations"], "summary": "Get an iteration with scores", "security": [ { "BearerApiKey": [] } ], "parameters": [ { "in": "path", "name": "experimentId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "iterationId", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Iteration with scores", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number" }, "experimentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "iteration": { "type": "number" }, "prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "overallNormalizedScore": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "evalNormalizedScore": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "createdAt": { "type": "string" } }, "required": [ "id", "experimentId", "iteration", "prompt", "overallNormalizedScore", "createdAt" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } } }, "/traces": { "get": { "tags": ["Traces"], "summary": "List traces", "security": [ { "BearerApiKey": [] } ], "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 50 } }, { "in": "query", "name": "offset", "schema": { "type": "integer", "default": 0 } }, { "in": "query", "name": "status", "schema": { "type": "string" } }, { "in": "query", "name": "ai_component", "schema": { "type": "string" } }, { "in": "query", "name": "start_after", "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "start_before", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "List of traces", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "traceId": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "aiComponentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "totalTokens": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "totalCostUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "durationMs": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "startTime": { "type": "string" }, "endTime": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "traceId", "name", "status", "aiComponentId", "totalTokens", "totalCostUsd", "durationMs", "startTime", "endTime" ], "additionalProperties": false } } }, "required": ["data"], "additionalProperties": false } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } }, "post": { "tags": ["Traces"], "summary": "Ingest OTLP traces", "description": "Accepts OpenTelemetry trace data in JSON or protobuf format", "security": [ { "BearerApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } }, "application/x-protobuf": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "200": { "description": "Traces ingested" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } }, "415": { "description": "Unsupported content type", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } } }, "/traces/{traceId}": { "get": { "tags": ["Traces"], "summary": "Get a trace by OpenTelemetry ID", "security": [ { "BearerApiKey": [] } ], "parameters": [ { "in": "path", "name": "traceId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Trace details with spans", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "traceId": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "aiComponentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "totalTokens": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "totalCostUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "durationMs": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "startTime": { "type": "string" }, "endTime": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "traceId", "name", "status", "aiComponentId", "totalTokens", "totalCostUsd", "durationMs", "startTime", "endTime" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } } }, "/traces/stats": { "get": { "tags": ["Traces"], "summary": "Get tracing statistics", "security": [ { "BearerApiKey": [] } ], "parameters": [ { "in": "query", "name": "days_back", "schema": { "type": "integer", "default": 30 } }, { "in": "query", "name": "ai_component", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tracing statistics" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } } } } }