{ "openapi": "3.1.1", "info": { "title": "Releval API", "description": "Welcome to 🥇 Releval's REST API documentation.\n\nReleval is a search relevance evaluation platform that gives you the tools to evaluate, track, and improve the relevance\nof results from your search system with confidence. Measure search quality with NDCG, MAP, MRR, and more across any search backend.\n\nThis is the REST API. Everything you can do in the UI, you can do here.\n\n", "termsOfService": "https://releval.co/eula", "contact": { "name": "Releval", "url": "https://releval.co/contact-us", "email": "hello@releval.co" }, "version": "v1" }, "paths": { "/api/v1/accounts/info": { "get": { "tags": [ "Accounts" ], "summary": "Get Info", "description": "Gets the authenticated member's account information", "operationId": "get-account-info", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Info" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } } }, "security": [ { "Bearer": [] } ] }, "post": { "tags": [ "Accounts" ], "summary": "Update Info", "description": "Updates the authenticated member's account information", "operationId": "update-account-info", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InfoRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/InfoRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Info" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/accounts/update-password": { "post": { "tags": [ "Accounts" ], "summary": "Update Password", "description": "Updates the authenticated member's account password", "operationId": "update-password", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePasswordRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/UpdatePasswordRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": {} } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/ai-judges": { "get": { "tags": [ "AI Judges" ], "summary": "List AI Judges", "description": "Lists all AI judges accessible to the current member. Admins see all judges; members see shared judges and their own.", "parameters": [ { "name": "page", "in": "query", "description": "The page number (1-based).", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "default": 1 } }, { "name": "page_size", "in": "query", "description": "The number of items per page.", "schema": { "maximum": 100, "minimum": 10, "type": "integer", "format": "int32", "default": 25 } }, { "name": "search", "in": "query", "description": "An optional search term to filter AI judges by name.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAiJudgesResponse" }, "example": { "ai_judges": [ { "id": "01JRVX6GG4XMSM55XBC3E518DY", "name": "Relevance Judge", "description": "Judges relevance of movie search results on a 0-4 scale.", "ai_provider_id": "01JRVX6GG4XMSM55XBC3E518E0", "ai_provider_type": "openai", "ai_provider_name": "OpenAI Production", "model": "gpt-4o", "prompt_template": "Rate the relevance of the result {{candidate.title}} for the query \"{{query}}\" on a scale of 0-4.", "max_concurrency": 5, "batch_size": 5, "include_images": false, "member_id": "01JRVX6GG4XMSM55XBC3E518E1", "created": "2026-05-10T09:00:00+00:00", "updated": "2026-05-13T10:30:00+00:00" } ], "page": 1, "page_size": 20, "total_count": 1, "total_pages": 1 } } } } }, "security": [ { "Bearer": [] } ] }, "post": { "tags": [ "AI Judges" ], "summary": "Create an AI Judge", "description": "Creates a new AI judge. Admins can create shared judges (no member_id) or personal judges. Members can only create personal judges.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAiJudgeRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CreateAiJudgeRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiJudgeResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } } } } }, "security": [ { "Bearer": [] } ] }, "delete": { "tags": [ "AI Judges" ], "summary": "Delete AI Judges", "description": "Deletes the AI judges specified by the given unique identifiers.", "parameters": [ { "name": "judge_id", "in": "query", "description": "The unique identifiers of the AI judges to delete.", "required": true, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "OK" }, "404": { "description": "Not Found", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/ai-judges/{judge_id}": { "get": { "tags": [ "AI Judges" ], "summary": "Get an AI Judge", "description": "Gets the details of an AI judge.", "parameters": [ { "name": "judge_id", "in": "path", "description": "The unique identifier of the AI judge.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiJudgeResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } } }, "security": [ { "Bearer": [] } ] }, "put": { "tags": [ "AI Judges" ], "summary": "Update an AI Judge", "description": "Updates an existing AI judge. Only the owner or an admin can update.", "parameters": [ { "name": "judge_id", "in": "path", "description": "The unique identifier of the AI judge.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAiJudgeRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/UpdateAiJudgeRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiJudgeResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/ai-judges/{judge_id}/test": { "post": { "tags": [ "AI Judges" ], "summary": "Test an AI Judge", "description": "Tests connectivity to an AI judge by sending a simple prompt. If the judge is configured\n to send candidate images, an additional multimodal probe verifies the model accepts image input.", "parameters": [ { "name": "judge_id", "in": "path", "description": "The unique identifier of the AI judge.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestAiJudgeResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/evaluations/runs/{run_id}/ai-judge": { "post": { "tags": [ "AI Judges" ], "summary": "Start AI Judging", "description": "Starts an AI judging run on a completed evaluation run.", "parameters": [ { "name": "run_id", "in": "path", "description": "The unique identifier of the evaluation run.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartAiJudgingRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/StartAiJudgingRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiJudgingRunResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/evaluations/runs/{run_id}/ai-judging-runs": { "get": { "tags": [ "AI Judges" ], "summary": "List AI Judging Runs", "description": "Lists all AI judging runs for an evaluation run.", "parameters": [ { "name": "run_id", "in": "path", "description": "The unique identifier of the evaluation run.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAiJudgingRunsResponse" }, "example": { "ai_judging_runs": [ { "id": "01JRVX6GG4XMSM55XBC3E518DY", "evaluation_run_id": "01JRVX6GG4XMSM55XBC3E518E2", "ai_judge_id": "01JRVX6GG4XMSM55XBC3E518E3", "ai_judge_name": "Relevance Judge", "ai_judge_provider_type": "openai", "status": "running", "progress": 0.75, "total_count": 200, "completed_count": 150, "failed_count": 2, "input_token_count": 125000, "output_token_count": 45000, "initiated_by_member_id": "01JRVX6GG4XMSM55XBC3E518E4", "created": "2026-05-13T10:30:00+00:00", "updated": "2026-05-13T10:45:00+00:00" } ] } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/ai-judging-runs/{judging_run_id}/cancel": { "post": { "tags": [ "AI Judges" ], "summary": "Cancel AI Judging Run", "description": "Cancels a running AI judging run.", "parameters": [ { "name": "judging_run_id", "in": "path", "description": "The unique identifier of the AI judging run.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "404": { "description": "Not Found", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/ai-providers": { "get": { "tags": [ "AI Providers" ], "summary": "List AI providers", "description": "Lists all AI providers accessible to the current member.", "parameters": [ { "name": "page", "in": "query", "description": "The page number (1-based).", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "default": 1 } }, { "name": "page_size", "in": "query", "description": "The number of items per page.", "schema": { "maximum": 100, "minimum": 10, "type": "integer", "format": "int32", "default": 25 } }, { "name": "search", "in": "query", "description": "An optional search term to filter AI providers by name.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAiProvidersResponse" }, "example": { "ai_providers": [ { "type": "openai", "id": "01JRVX6GG4XMSM55XBC3E518DY", "name": "OpenAI Production", "member_id": "01JRVX6GG4XMSM55XBC3E518E0", "created": "2026-05-10T09:00:00+00:00", "updated": "2026-05-13T10:30:00+00:00" } ], "page": 1, "page_size": 20, "total_count": 1, "total_pages": 1 } } } } }, "security": [ { "Bearer": [] } ] }, "post": { "tags": [ "AI Providers" ], "summary": "Create an AI provider", "description": "Creates a new AI provider. Admins can create shared providers or personal providers.\n Members can only create personal providers.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAiProviderRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CreateAiProviderRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiProviderResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/ai-providers/{provider_id}": { "get": { "tags": [ "AI Providers" ], "summary": "Get an AI provider", "description": "Returns the configuration of an AI provider.", "parameters": [ { "name": "provider_id", "in": "path", "description": "The unique identifier of the AI provider.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiProviderResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } } }, "security": [ { "Bearer": [] } ] }, "put": { "tags": [ "AI Providers" ], "summary": "Update an AI provider", "description": "Updates the provider name and connection details. Provider type cannot be changed; the request\n type must match the existing provider's type. For secret fields, omitting the field\n or sending null keeps the existing value. Sending a value rotates the secret.", "parameters": [ { "name": "provider_id", "in": "path", "description": "The unique identifier of the AI provider.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAiProviderRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/UpdateAiProviderRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiProviderResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } } }, "security": [ { "Bearer": [] } ] }, "delete": { "tags": [ "AI Providers" ], "summary": "Delete an AI provider", "description": "Returns 409 if any AI judges still reference this provider.", "parameters": [ { "name": "provider_id", "in": "path", "description": "The unique identifier of the AI provider to delete.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "404": { "description": "Not Found", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } }, "409": { "description": "Conflict", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.8", "title": "Conflict.", "status": 409 } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.8", "title": "Conflict.", "status": 409 } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.8", "title": "Conflict.", "status": 409 } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/ai-providers/{provider_id}/test": { "post": { "tags": [ "AI Providers" ], "summary": "Test an AI provider", "description": "Verifies that the configured credentials and connection details successfully reach\n the provider. The caller specifies which model to test against.", "parameters": [ { "name": "provider_id", "in": "path", "description": "The unique identifier of the AI provider.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestAiProviderRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/TestAiProviderRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestAiProviderResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/analysis": { "get": { "tags": [ "Analysis" ], "summary": "List Analyses", "description": "Lists the available analyses.", "operationId": "list-analysis", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAnalysesResponse" }, "example": { "analyses": [ { "id": "01JRVX6GG4XMSM55XBC3E518DY", "name": "Search relevance baseline", "created": "2026-05-13T10:30:00+00:00", "executions_processed": 100, "executions_count": 100, "status": "completed" }, { "id": "01JRVX6GG4XMSM55XBC3E518DZ", "name": "Title boost experiment", "created": "2026-05-13T11:00:00+00:00", "executions_processed": 42, "executions_count": 100, "status": "running" } ] } } } } }, "security": [ { "Bearer": [] } ] }, "delete": { "tags": [ "Analysis" ], "summary": "Delete Analyses", "description": "Deletes the analyses for given IDs", "operationId": "delete-analysis", "parameters": [ { "name": "analysis_id", "in": "query", "description": "The unique identifiers of the analyses to delete.", "required": true, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "OK" } }, "security": [ { "Bearer": [] } ] }, "post": { "tags": [ "Analysis" ], "summary": "Create Analysis", "description": "Creates a new analysis by executing queries against a search endpoint.", "operationId": "create-analysis", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAnalysisRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CreateAnalysisRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAnalysisResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.3", "title": "Forbidden.", "status": 403 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } }, "default": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/analysis/{analysis_id}": { "get": { "tags": [ "Analysis" ], "summary": "Get Analysis", "description": "Gets the analysis by its unique identifier.", "operationId": "get-analysis", "parameters": [ { "name": "analysis_id", "in": "path", "description": "The unique identifier of the analysis.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAnalysisResponse" }, "example": { "id": "01JRVX6GG4XMSM55XBC3E518DY", "name": "Search relevance baseline", "created": "2026-05-13T10:30:00+00:00", "executions_processed": 42, "queries": [ { "name": "Shrek", "baseline": true, "mean_duration_ms": 45.6 }, { "name": "The Godfather", "baseline": false, "mean_duration_ms": 38.2 }, { "name": "The Matrix", "baseline": false, "mean_duration_ms": 52.1 } ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/analysis/upload": { "post": { "tags": [ "Analysis" ], "summary": "Upload Analysis", "description": "Upload an existing query executions file for analysis.", "operationId": "upload-analysis", "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/IFormFile" }, "name": { "type": "string" }, "count": { "type": "integer", "format": "int32" } } } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAnalysisResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.3", "title": "Forbidden.", "status": 403 } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/analysis/{analysis_id}/status": { "get": { "tags": [ "Analysis" ], "summary": "Analysis Status", "description": "Gets the status of an analysis. Used to determine if any analysis has started, is running, or\n has completed.", "operationId": "get-analysis-status", "parameters": [ { "name": "analysis_id", "in": "path", "description": "The unique identifier of the analysis.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalysisStatusResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/analysis/{analysis_id}/metrics": { "get": { "tags": [ "Analysis" ], "summary": "Analysis Metrics", "description": "Gets the metrics from an analysis for the given query name.", "operationId": "get-query-metrics", "parameters": [ { "name": "analysis_id", "in": "path", "description": "The unique identifier of the analysis.", "required": true, "schema": { "type": "string" } }, { "name": "query_name", "in": "query", "description": "The name of the query to get metrics for.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalysisMetricsResponse" }, "example": { "name": "Shrek", "statistics": [ { "name": "NDCG", "count": 100, "count_one": 25, "count_zero": 10, "mean": 0.75, "variance": 0.05, "standard_deviation": 0.22, "kurtosis": 2.5, "skewness": 0.1 } ], "metrics": [ { "name": "NDCG", "bucket_start": 0, "bucket_count": 10 }, { "name": "NDCG", "bucket_start": 0.5, "bucket_count": 25 }, { "name": "NDCG", "bucket_start": 1, "bucket_count": 65 } ] } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/app-clients": { "get": { "tags": [ "App Clients" ], "summary": "List App Clients", "description": "Lists the app clients available for the authenticated member.\n \n An app client provides access to Releval APIs, through [OAuth 2.0 authentication](https://www.oauth.com/).\n A unique `client_id` and `client_secret` are generated upon creation and returned in the response.\n The `client_secret` is only provided **once** upon creation, so be sure to make a note of it when presented.", "operationId": "list-app-clients", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAppClientsResponse" }, "example": { "app_clients": [ { "id": "01JRVX6GG4XMSM55XBC3E518DY", "name": "Search Indexer", "description": "App client used by the indexing pipeline", "roles": [ "Admin" ], "client_id": "01JRVX6GG4XMSM55XBC3E518E0", "client_secret_hint": "...A1b2", "last_used": "2026-05-13T10:30:00+00:00", "created": "2026-05-01T09:00:00+00:00", "updated": "2026-05-10T12:00:00+00:00" } ] } } } } }, "security": [ { "Bearer": [] } ] }, "post": { "tags": [ "App Clients" ], "summary": "Create App Client", "description": "Creates a new app client.\n \n An app client provides access to Releval APIs, through [OAuth 2.0 authentication](https://www.oauth.com/).\n A unique `client_id` and `client_secret` are generated upon creation and returned in the response.\n The `client_secret` is only provided **once** upon creation, so be sure to make a note of it when presented.", "operationId": "create-app-client", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAppClientRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CreateAppClientRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAppClientResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "Bad Request.", "status": 400 } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.3", "title": "Forbidden.", "status": 403 } } } } }, "security": [ { "Bearer": [] } ] }, "delete": { "tags": [ "App Clients" ], "summary": "Delete App Clients", "description": "Deletes the app clients for the given unique identifiers", "operationId": "delete-app-clients", "parameters": [ { "name": "app_client_id", "in": "query", "description": "The unique identifiers of the app clients to delete.", "required": true, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "OK" } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/app-clients/{app_client_id}/regenerate-secret": { "post": { "tags": [ "App Clients" ], "summary": "Regenerate Secret", "description": "Generates a new client secret for the app client. The old client secret is overwritten.\n \n An app client provides access to Releval APIs, through [OAuth 2.0 authentication](https://www.oauth.com/).\n A unique `client_id` and `client_secret` are generated upon creation and returned in the response.\n The `client_secret` is only provided **once** upon creation, so be sure to make a note of it when presented.", "operationId": "regenerate-app-client-secret", "parameters": [ { "name": "app_client_id", "in": "path", "description": "The unique identifier of the app client.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAppClientResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/app-clients/{app_client_id}": { "get": { "tags": [ "App Clients" ], "summary": "Get App Client", "description": "Gets an app client by its unique identifier.\n \n An app client provides access to Releval APIs, through [OAuth 2.0 authentication](https://www.oauth.com/).\n A unique `client_id` and `client_secret` are generated upon creation and returned in the response.\n The `client_secret` is only provided **once** upon creation, so be sure to make a note of it when presented.", "operationId": "get-app-client", "parameters": [ { "name": "app_client_id", "in": "path", "description": "The unique identifier of the app client.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppClientResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/app-clients/authentication-url": { "get": { "tags": [ "App Clients" ], "summary": "Get Authentication URL", "description": "Returns the OAuth 2.0 authentication URL to use to authenticate app client requests.", "operationId": "get-authentication-url", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationUrlResponse" } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/auth/register": { "post": { "tags": [ "Auth" ], "summary": "Register Member", "description": "Registers a new member using email and password. The member will receive an email to confirm their email address.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/RegisterRequest" } } }, "required": true }, "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } } } } } } }, "/api/v1/corpora": { "get": { "tags": [ "Corpora" ], "summary": "List Corpora", "description": "Lists all corpora.", "operationId": "list-corpora", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCorporaResponse" }, "example": { "corpora": [ { "id": "01JRVX6GG4XMSM55XBC3E518DY", "name": "Movies", "description": "Movies from TMDB", "created": "2026-05-13T10:30:00+00:00", "updated": "2026-05-14T11:00:00+00:00", "endpoint_count": 3 }, { "id": "01JRVX6GG4XMSM55XBC3E518DZ", "name": "Products", "description": "E-commerce product catalogue", "created": "2026-05-13T11:00:00+00:00", "endpoint_count": 1 } ] } } } } }, "security": [ { "Bearer": [] } ] }, "post": { "tags": [ "Corpora" ], "summary": "Create Corpus", "description": "Creates a new corpus representing a document collection.", "operationId": "create-corpus", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCorpusRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CreateCorpusRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CorpusResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } } } } }, "security": [ { "Bearer": [] } ] }, "delete": { "tags": [ "Corpora" ], "summary": "Delete Corpora", "description": "Deletes the corpora with the given IDs. A corpus cannot be deleted if it has associated endpoints.", "operationId": "delete-corpora", "parameters": [ { "name": "corpus_id", "in": "query", "description": "The unique identifiers of the corpora to delete.", "required": true, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "OK" }, "409": { "description": "Conflict", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.8", "title": "Conflict.", "status": 409 } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.8", "title": "Conflict.", "status": 409 } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.8", "title": "Conflict.", "status": 409 } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/corpora/{id}": { "get": { "tags": [ "Corpora" ], "summary": "Get Corpus", "description": "Gets a corpus by its unique identifier.", "operationId": "get-corpus", "parameters": [ { "name": "id", "in": "path", "description": "The unique identifier of the corpus.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CorpusResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } } }, "security": [ { "Bearer": [] } ] }, "put": { "tags": [ "Corpora" ], "summary": "Update Corpus", "description": "Updates an existing corpus.", "operationId": "update-corpus", "parameters": [ { "name": "id", "in": "path", "description": "The unique identifier of the corpus.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCorpusRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/UpdateCorpusRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CorpusResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/endpoints": { "get": { "tags": [ "Search Endpoints" ], "summary": "List Endpoints", "description": "Lists the search endpoints available to execute requests against.", "operationId": "list-endpoints", "parameters": [ { "name": "page", "in": "query", "description": "The page number (1-based).", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "default": 1 } }, { "name": "page_size", "in": "query", "description": "The number of items per page.", "schema": { "maximum": 100, "minimum": 10, "type": "integer", "format": "int32", "default": 25 } }, { "name": "search", "in": "query", "description": "An optional search term to filter endpoints by name.", "schema": { "type": "string" } }, { "name": "corpus", "in": "query", "description": "An optional corpus ID to filter endpoints by their associated corpus.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEndpointsResponse" }, "example": { "endpoints": [ { "id": "01JRVX6GG4XMSM55XBC3E518DY", "name": "Movies", "description": "Movies from TMDB", "type": "elasticsearch", "url": "https://localhost:9200/movies/_search", "method": "GET", "authentication_type": "basic", "corpus_id": "01JRVX6GG4XMSM55XBC3E518DZ", "candidates_mapping": "{ total: (hits.total.value || hits.total), candidates: hits.hits[].{ id: _id, title: _source.title, image: _source.image, fields: _source } }" } ], "page": 1, "page_size": 20, "total_count": 1, "total_pages": 1 } } } } }, "security": [ { "Bearer": [] } ] }, "post": { "tags": [ "Search Endpoints" ], "summary": "Create Endpoint", "description": "Creates a new search endpoint.", "operationId": "create-endpoint", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEndpointRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CreateEndpointRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointResponse" }, "example": { "id": "01JRVX6GG4XMSM55XBC3E518DY", "name": "Movies", "description": "Movies from TMDB", "type": "elasticsearch", "url": "https://localhost:9200/movies/_search", "method": "GET", "authentication_type": "basic", "corpus_id": "01JRVX6GG4XMSM55XBC3E518DZ", "candidates_mapping": "{ total: (hits.total.value || hits.total), candidates: hits.hits[].{ id: _id, title: _source.title, image: _source.image, fields: _source } }" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.3", "title": "Forbidden.", "status": 403 } } } } }, "security": [ { "Bearer": [] } ] }, "delete": { "tags": [ "Search Endpoints" ], "summary": "Delete Endpoints", "description": "Deletes the search endpoints specified by the given unique identifiers.", "operationId": "delete-endpoints", "parameters": [ { "name": "endpoint_id", "in": "query", "description": "The unique identifiers of the search endpoints to delete.", "required": true, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "OK" }, "404": { "description": "Not Found", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/endpoints/{endpoint_id}": { "get": { "tags": [ "Search Endpoints" ], "summary": "Get Endpoint", "description": "Gets a search endpoint by its unique identifier.", "operationId": "get-endpoint", "parameters": [ { "name": "endpoint_id", "in": "path", "description": "The unique identifier of the search endpoint.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointResponse" }, "example": { "id": "01JRVX6GG4XMSM55XBC3E518DY", "name": "Movies", "description": "Movies from TMDB", "type": "elasticsearch", "url": "https://localhost:9200/movies/_search", "method": "GET", "authentication_type": "basic", "corpus_id": "01JRVX6GG4XMSM55XBC3E518DZ", "candidates_mapping": "{ total: (hits.total.value || hits.total), candidates: hits.hits[].{ id: _id, title: _source.title, image: _source.image, fields: _source } }" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } } }, "security": [ { "Bearer": [] } ] }, "put": { "tags": [ "Search Endpoints" ], "summary": "Update Endpoint", "description": "Updates the search endpoint given by the unique identifier.", "operationId": "update-endpoint", "parameters": [ { "name": "endpoint_id", "in": "path", "description": "The unique identifier of the search endpoint.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEndpointRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/UpdateEndpointRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointResponse" }, "example": { "id": "01JRVX6GG4XMSM55XBC3E518DY", "name": "Movies", "description": "Movies from TMDB", "type": "elasticsearch", "url": "https://localhost:9200/movies/_search", "method": "GET", "authentication_type": "basic", "corpus_id": "01JRVX6GG4XMSM55XBC3E518DZ", "candidates_mapping": "{ total: (hits.total.value || hits.total), candidates: hits.hits[].{ id: _id, title: _source.title, image: _source.image, fields: _source } }" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/endpoints/{endpoint_id}/auth": { "put": { "tags": [ "Search Endpoints" ], "summary": "Update Authentication", "description": "Updates the authentication credentials for a search endpoint given by the unique identifier.\n \n Authentication credentials are encrypted at rest using [AES encryption](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard)\n and cannot be retrieved by members once set; they can only be updated, or removed by making a request an empty body.", "operationId": "update-endpoint-auth", "parameters": [ { "name": "endpoint_id", "in": "path", "description": "The unique identifier of the search endpoint.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AuthenticationCredentials" } ] } }, "application/*+json": { "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AuthenticationCredentials" } ] } } } }, "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } }, "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } }, "text/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } } } }, "404": { "description": "Not Found", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/endpoints/{endpoint_id}/test": { "post": { "tags": [ "Search Endpoints" ], "summary": "Test Existing Endpoint", "description": "Tests an existing search endpoint with the given unique identifier to verify that queries can be executed against it.\n \n The response can originate from the Releval API or from the search endpoint; when a response\n is from the search endpoint, it includes an `X-Eval-Response` HTTP header name with a value\n set to `endpoint`.", "operationId": "test-endpoint-id", "parameters": [ { "name": "endpoint_id", "in": "path", "description": "The unique identifier of the search endpoint.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestEndpointRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/TestEndpointRequest" } } }, "required": true }, "responses": { "400": { "description": "Bad Request", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } } } }, "404": { "description": "Not Found", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } }, "default": { "description": "", "content": { "text/plain": { "schema": { "type": "string" } }, "application/problem+json": { "schema": { "type": "string" } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/endpoints/test": { "post": { "tags": [ "Search Endpoints" ], "summary": "Test Endpoint", "description": "Tests a search endpoint to verify that queries can be executed against it.\n \n The response can originate from the Releval API or from the search endpoint; when a response\n is from the search endpoint, it includes an `X-Eval-Response` HTTP header name with a value\n set to `endpoint`.", "operationId": "test-endpoint", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestEndpointAuthRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/TestEndpointAuthRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "type": "string" } }, "application/problem+json": { "schema": { "type": "string" } } } }, "400": { "description": "Bad Request", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } } } }, "500": { "description": "Internal Server Error", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "default": { "description": "", "content": { "text/plain": { "schema": { "type": "string" } }, "application/problem+json": { "schema": { "type": "string" } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/evaluations/{evaluation_id}/runs": { "post": { "tags": [ "Evaluation Runs" ], "summary": "Create Evaluation Run", "description": "Creates an evaluation run for the evaluation specified by the given ID.", "operationId": "create-evaluation-run", "parameters": [ { "name": "evaluation_id", "in": "path", "description": "The unique identifier of the evaluation.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEvaluationRunRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CreateEvaluationRunRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationRunResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.3", "title": "Forbidden.", "status": 403 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } } }, "security": [ { "Bearer": [] } ] }, "get": { "tags": [ "Evaluation Runs" ], "summary": "List Evaluation Runs", "description": "Gets the evaluation runs for an evaluation specified by the given ID.", "operationId": "list-evaluation-runs", "parameters": [ { "name": "evaluation_id", "in": "path", "description": "The unique identifier of the evaluation.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEvaluationRunsResponse" }, "example": { "runs": [ { "id": "01JRVX6GG4XMSM55XBC3E518DY", "evaluation_id": "01JRVX6GG4XMSM55XBC3E518E1", "name": "Movies baseline run", "description": "Initial evaluation against the Movies endpoint", "scale": "graded", "metrics": { "NDCG@10": 0.847, "MAP": 0.612 }, "status": "completed", "created": "2026-05-13T10:30:00+00:00", "member_id": "01JRVX6GG4XMSM55XBC3E518M1", "query_count": 100, "candidates_mapping": "{ total: hits.total.value, candidates: hits.hits[].{ id: _id, title: _source.title, fields: _source } }", "content_type": "json", "body": "{ \"query\": { \"match\": { \"title\": \"{{query}}\" } } }", "tags": [ "commit:abc123", "staging" ], "corpus_id": "01JRVX6GG4XMSM55XBC3E518DZ" } ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/evaluations/runs/{run_id}": { "get": { "tags": [ "Evaluation Runs" ], "summary": "Get Evaluation Run", "description": "Gets the evaluation run for the given unique identifier.", "operationId": "get-evaluation-run", "parameters": [ { "name": "run_id", "in": "path", "description": "The unique identifier of the evaluation run.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationRunResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/evaluations/runs/{run_id}/clone": { "post": { "tags": [ "Evaluation Runs" ], "summary": "Clone Evaluation Run", "description": "Clones an existing evaluation run with the given unique identifier and starts it.", "operationId": "clone-evaluation-run", "parameters": [ { "name": "run_id", "in": "path", "description": "The unique identifier of the evaluation run.", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationRunResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/evaluations/runs/{run_id}/start": { "post": { "tags": [ "Evaluation Runs" ], "summary": "Start Evaluation Run", "description": "Starts an evaluation run.", "operationId": "start-evaluation-run", "parameters": [ { "name": "run_id", "in": "path", "description": "The unique identifier of the evaluation run.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationRunStatusResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/evaluations/runs/{run_id}/lock": { "post": { "tags": [ "Evaluation Runs" ], "summary": "Lock Evaluation Run", "description": "Locks a completed evaluation run, preventing any further judgment modifications.\n Only runs with a 'completed' status can be locked.", "operationId": "lock-evaluation-run", "parameters": [ { "name": "run_id", "in": "path", "description": "The unique identifier of the evaluation run.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationRunStatusResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "Bad Request.", "status": 400 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/evaluations/runs/{run_id}/stop": { "post": { "tags": [ "Evaluation Runs" ], "summary": "Stop Evaluation Run", "description": "Stops a queued or running evaluation run. Queries that have already completed\n are preserved; only unprocessed queries are skipped.", "operationId": "stop-evaluation-run", "parameters": [ { "name": "run_id", "in": "path", "description": "The unique identifier of the evaluation run.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationRunStatusResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "Bad Request.", "status": 400 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/evaluations/runs/{run_id}/tags": { "put": { "tags": [ "Evaluation Runs" ], "summary": "Update Evaluation Run Tags", "description": "Updates the tags on an evaluation run. Tags can be updated on runs in any status.\n Pass an empty dictionary to clear all tags.", "operationId": "update-evaluation-run-tags", "parameters": [ { "name": "run_id", "in": "path", "description": "The unique identifier of the evaluation run.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEvaluationRunTagsRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/UpdateEvaluationRunTagsRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationRunResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/evaluations/{evaluation_id}/metrics/trends": { "get": { "tags": [ "Evaluation Runs" ], "summary": "Get Metric Trends", "description": "Returns metric values for all completed or locked runs in an evaluation, ordered by creation date.\n Includes config change detection between consecutive runs.", "operationId": "get-metric-trends", "parameters": [ { "name": "evaluation_id", "in": "path", "description": "The unique identifier of the evaluation.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricTrendsResponse" }, "example": { "runs": [ { "run_id": "01JRVX6GG4XMSM55XBC3E518DY", "run_name": "Movies baseline run", "created": "2026-05-13T10:30:00+00:00", "status": "completed", "metrics": { "NDCG@10": 0.847, "MAP": 0.612, "MRR@10": 0.755 }, "config_changed": false }, { "run_id": "01JRVX6GG4XMSM55XBC3E518E2", "run_name": "Movies tuned run", "created": "2026-05-14T10:30:00+00:00", "status": "completed", "metrics": { "NDCG@10": 0.872, "MAP": 0.645, "MRR@10": 0.781 }, "config_changed": true, "config_changes": [ "body template changed" ] } ], "metrics": [ "NDCG@10", "MAP", "MRR@10" ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/evaluations/runs/{run_id}/compare/{baseline_run_id}": { "get": { "tags": [ "Evaluation Runs" ], "summary": "Compare Evaluation Runs", "description": "Compares two evaluation runs, showing run-level metric deltas and per-query metric breakdowns.\n Both runs must belong to the same evaluation and have a completed or locked status.", "operationId": "compare-evaluation-runs", "parameters": [ { "name": "run_id", "in": "path", "description": "The unique identifier of the current evaluation run.", "required": true, "schema": { "type": "string" } }, { "name": "baseline_run_id", "in": "path", "description": "The unique identifier of the baseline evaluation run to compare against.", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "The page number (1-based).", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "default": 1 } }, { "name": "pageSize", "in": "query", "description": "The number of items per page.", "schema": { "maximum": 100, "minimum": 1, "type": "integer", "format": "int32", "default": 50 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunComparisonResponse" }, "example": { "run_id": "01JRVX6GG4XMSM55XBC3E518DY", "baseline_run_id": "01JRVX6GG4XMSM55XBC3E518D1", "run_name": "Movies tuned run", "baseline_name": "Movies baseline run", "metrics_comparison": [ { "name": "NDCG@10", "run_value": 0.872, "baseline_value": 0.847, "delta": 0.025, "relative_delta": 0.0295 }, { "name": "MAP", "run_value": 0.645, "baseline_value": 0.612, "delta": 0.033, "relative_delta": 0.0539 } ], "query_comparisons": [ { "query_item_id": "12345", "query": { "query": "Shrek" }, "run_metrics": { "NDCG@10": 0.872, "MAP": 0.645 }, "baseline_metrics": { "NDCG@10": 0.847, "MAP": 0.612 }, "status": "improved" } ], "summary": { "improved": 42, "regressed": 15, "unchanged": 193 }, "config_changes": [ "body template changed" ], "page": 1, "page_size": 50, "total_count": 250, "total_pages": 5 } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "Bad Request.", "status": 400 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/evaluations/runs": { "delete": { "tags": [ "Evaluation Runs" ], "summary": "Delete Evaluation Runs", "description": "Deletes the evaluation runs specified by the given unique identifiers.", "operationId": "delete-evaluation-runs", "parameters": [ { "name": "run_id", "in": "query", "description": "The unique identifiers of the evaluation runs to delete.", "required": true, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "OK", "content": { "application/json": {} } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.8", "title": "Conflict.", "status": 409 } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/evaluations/runs/{run_id}/queries": { "get": { "tags": [ "Evaluation Runs" ], "summary": "List Queries", "description": "Lists the evaluation queries for a specific evaluation run.", "operationId": "list-evaluation-queries", "parameters": [ { "name": "run_id", "in": "path", "description": "The unique identifier of the evaluation run.", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "The page number (1-based).", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "default": 1 } }, { "name": "page_size", "in": "query", "description": "The number of items per page.", "schema": { "maximum": 100, "minimum": 10, "type": "integer", "format": "int32", "default": 10 } }, { "name": "sort", "in": "query", "description": "Optional sort field. Use \"query\" to sort by query text, or a metric name (e.g. \"NDCG@10\") to sort by metric value", "schema": { "type": "string" } }, { "name": "direction", "in": "query", "description": "Sort direction: \"asc\" (default) or \"desc\"", "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "Optional search term to filter queries by text (case-insensitive)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEvaluationQueriesResponse" }, "example": { "queries": [ { "id": "01JRVX6GG4XMSM55XBC3E518DY", "query": { "query": "Shrek" }, "execution": { "body": "{ \"query\": { \"match\": { \"title\": \"Shrek\" } } }", "url": "https://localhost:9200/movies/_search?size=10", "method": "POST", "content_type": "application/json" }, "total_candidates": 1500, "status_code": 200, "failed": false, "query_item_id": "12345", "oid": "67890", "created": "2026-05-13T10:30:00+00:00", "metrics": { "NDCG@10": 0.847 } }, { "id": "01JRVX6GG4XMSM55XBC3E518DZ", "query": { "query": "The Matrix" }, "execution": { "body": "{ \"query\": { \"match\": { \"title\": \"The Matrix\" } } }", "url": "https://localhost:9200/movies/_search?size=10", "method": "POST", "content_type": "application/json" }, "total_candidates": 1200, "status_code": 200, "failed": false, "query_item_id": "12346", "oid": "67891", "created": "2026-05-13T10:30:00+00:00", "metrics": { "NDCG@10": 0.792 } } ], "page": 1, "page_size": 50, "total_count": 2, "total_pages": 1 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/evaluations/runs/queries/{query_id}/results": { "get": { "tags": [ "Evaluation Runs" ], "summary": "List Results", "description": "Lists the results for a specific query in an evaluation run. Results are paginated.", "operationId": "list-evaluation-query-results", "parameters": [ { "name": "query_id", "in": "path", "description": "The unique identifier of the evaluation query.", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "The page number (1-based).", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "default": 1 } }, { "name": "page_size", "in": "query", "description": "The number of items per page.", "schema": { "maximum": 100, "minimum": 10, "type": "integer", "format": "int32", "default": 10 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEvaluationQueryResultsResponse" }, "example": { "evaluation_run_id": "01JRVX6GG4XMSM55XBC3E518DY", "results": [ { "id": "01JRVX6GG4XMSM55XBC3E518R1", "position": 1, "evaluation_query_id": "01JRVX6GG4XMSM55XBC3E518DB", "created": "2026-05-13T10:30:00+00:00", "candidate": { "id": "tt0126029", "title": "Shrek", "fields": { "year": 2001 } } }, { "id": "01JRVX6GG4XMSM55XBC3E518R2", "position": 2, "evaluation_query_id": "01JRVX6GG4XMSM55XBC3E518DB", "created": "2026-05-13T10:30:00+00:00", "candidate": { "id": "tt0298148", "title": "Shrek 2", "fields": { "year": 2004 } } } ], "page": 1, "page_size": 50, "total_count": 2, "total_pages": 1 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/evaluations/runs/{run_id}/next-result": { "get": { "tags": [ "Evaluation Runs" ], "summary": "Get Next Result for Evaluation", "description": "Gets the next unrated result for evaluation by the current member. Results are prioritized\n by those with no judgments from anyone first, then by position within each query.", "operationId": "get-next-result-for-evaluation", "parameters": [ { "name": "run_id", "in": "path", "description": "The unique identifier of the evaluation run.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NextResultForEvaluationResponse" }, "example": { "result": { "id": "01JRVX6GG4XMSM55XBC3E518R1", "position": 1, "evaluation_query_id": "01JRVX6GG4XMSM55XBC3E518DB", "created": "2026-05-13T10:30:00+00:00", "candidate": { "id": "tt0126029", "title": "Shrek", "fields": { "year": 2001 } } }, "query": { "id": "01JRVX6GG4XMSM55XBC3E518DB", "query": { "query": "Shrek" } }, "scale": "graded", "remaining_count": 42, "total_count": 250, "run_id": "01JRVX6GG4XMSM55XBC3E518DY", "run_name": "Movies baseline run", "evaluation_name": "Movies relevance evaluation", "corpus_id": "01JRVX6GG4XMSM55XBC3E518DZ", "oid": "67890" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/evaluations": { "post": { "tags": [ "Evaluations" ], "summary": "Create Evaluation", "description": "Creates a new evaluation.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEvaluationRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CreateEvaluationRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.3", "title": "Forbidden.", "status": 403 } } } } }, "security": [ { "Bearer": [] } ] }, "get": { "tags": [ "Evaluations" ], "summary": "List Evaluations", "description": "Lists the available evaluations.", "parameters": [ { "name": "page", "in": "query", "description": "The page number (1-based).", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "default": 1 } }, { "name": "page_size", "in": "query", "description": "The number of items per page.", "schema": { "maximum": 100, "minimum": 10, "type": "integer", "format": "int32", "default": 25 } }, { "name": "search", "in": "query", "description": "An optional search term to filter evaluations by name.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEvaluationsResponse" }, "example": { "evaluations": [ { "id": "01JRVX6GG4XMSM55XBC3E518E6", "name": "Popular Movies", "description": "Popular movies in the last week", "endpoint_id": "01JRVX6GG4XMSM55XBC3E518DY", "query_template_id": "01JRVX6GG4XMSM55XBC3E518E3", "query_set_id": "01JRVX6GG4XMSM55XBC3E518E2", "created": "2026-05-13T10:30:00+00:00", "updated": "2026-05-14T09:15:00+00:00" } ], "page": 1, "page_size": 20, "total_count": 1, "total_pages": 1 } } } } }, "security": [ { "Bearer": [] } ] }, "delete": { "tags": [ "Evaluations" ], "summary": "Delete Evaluations", "description": "Deletes the evaluations for the given unique identifiers.", "operationId": "delete-evaluations", "parameters": [ { "name": "evaluation_id", "in": "query", "description": "The unique identifiers of the evaluations to delete.", "required": true, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "OK" }, "404": { "description": "Not Found", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/evaluations/{evaluation_id}": { "put": { "tags": [ "Evaluations" ], "summary": "Update Evaluation", "description": "Updates an existing evaluation.", "parameters": [ { "name": "evaluation_id", "in": "path", "description": "The unique identifier of the evaluation.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEvaluationRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/UpdateEvaluationRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } } }, "security": [ { "Bearer": [] } ] }, "get": { "tags": [ "Evaluations" ], "summary": "Get Evaluation", "description": "Gets an evaluation by its unique identifier.", "parameters": [ { "name": "evaluation_id", "in": "path", "description": "The unique identifier of the evaluation.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/analysis/{analysis_id}/executions": { "get": { "tags": [ "Analysis" ], "summary": "List Executions", "description": "Lists the executions for a given Analysis ID.", "operationId": "list-executions", "parameters": [ { "name": "analysis_id", "in": "path", "description": "The unique identifier of the analysis.", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "The page number (1-based).", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "default": 1 } }, { "name": "page_size", "in": "query", "description": "The number of items per page.", "schema": { "maximum": 100, "minimum": 10, "type": "integer", "format": "int32", "default": 25 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListExecutionsResponse" }, "example": { "executions": [ { "id": "01JRVX6GG4XMSM55XBC3E518DY", "name": "Shrek", "execution_index": 0, "baseline": true, "query": { "method": "POST", "endpoint": "/movies/_search", "content_type": "application/json", "body": "{ \"query\": { \"match\": { \"title\": \"Shrek\" } } }" }, "result": { "candidates": [ { "id": "808", "title": "Shrek", "image": "https://image.tmdb.org/t/p/w500/shrek.jpg" } ], "total": 1 }, "duration_ms": 45.6 } ], "page": 1, "page_size": 25, "total_count": 100, "total_pages": 4 } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/analysis/{analysis_id}/executions/{execution_index}": { "get": { "tags": [ "Analysis" ], "summary": "Get Executions", "description": "Gets the executions for the given Analysis ID and line number.", "operationId": "get-executions", "parameters": [ { "name": "analysis_id", "in": "path", "description": "The unique identifier of the analysis.", "required": true, "schema": { "type": "string" } }, { "name": "execution_index", "in": "path", "description": "The index for the executions within the analysis.", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ExecutionResponse" } } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/features/training": { "post": { "tags": [ "Features" ], "summary": "Create Training Data", "description": "Creates training data of feature values for a judgment list", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTrainingDataRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CreateTrainingDataRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CreateTrainingDataRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/CreateTrainingDataResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/CreateTrainingDataResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CreateTrainingDataResponse" } } } }, "400": { "description": "Bad Request", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } }, "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } }, "text/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/judgmentlists/upload": { "post": { "tags": [ "Judgment Lists" ], "summary": "Upload Judgment List", "description": "Creates a new Judgment List by uploading a file of judgments", "operationId": "upload-judgment-list", "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "judgments": { "$ref": "#/components/schemas/IFormFile" }, "name": { "type": "string" }, "type": { "type": "string" }, "scale": { "$ref": "#/components/schemas/EvaluationScale" }, "corpus_id": { "type": "string" } } } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JudgmentListResponse" }, "example": { "id": "01JRVX6GG4XMSM55XBC3E518DY", "name": "Movies judgments", "created": "2026-05-13T10:30:00+00:00", "type": "explicit", "member_id": "01JRVX6GG4XMSM55XBC3E518E0", "scale": "graded", "corpus_id": "01JRVX6GG4XMSM55XBC3E518DZ", "judgment_stats": { "count": 1500, "min_grade": 0, "max_grade": 4 } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.3", "title": "Forbidden.", "status": 403 } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/judgmentlists/{id}": { "get": { "tags": [ "Judgment Lists" ], "summary": "Get Judgment List", "description": "Gets a Judgment List by ID.", "operationId": "get-judgment-list", "parameters": [ { "name": "id", "in": "path", "description": "The unique identifier of the judgment list.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/JudgmentListResponse" }, "example": { "id": "01JRVX6GG4XMSM55XBC3E518DY", "name": "Movies judgments", "created": "2026-05-13T10:30:00+00:00", "type": "explicit", "member_id": "01JRVX6GG4XMSM55XBC3E518E0", "scale": "graded", "corpus_id": "01JRVX6GG4XMSM55XBC3E518DZ", "judgment_stats": { "count": 1500, "min_grade": 0, "max_grade": 4 } } }, "application/json": { "schema": { "$ref": "#/components/schemas/JudgmentListResponse" }, "example": { "id": "01JRVX6GG4XMSM55XBC3E518DY", "name": "Movies judgments", "created": "2026-05-13T10:30:00+00:00", "type": "explicit", "member_id": "01JRVX6GG4XMSM55XBC3E518E0", "scale": "graded", "corpus_id": "01JRVX6GG4XMSM55XBC3E518DZ", "judgment_stats": { "count": 1500, "min_grade": 0, "max_grade": 4 } } }, "text/json": { "schema": { "$ref": "#/components/schemas/JudgmentListResponse" }, "example": { "id": "01JRVX6GG4XMSM55XBC3E518DY", "name": "Movies judgments", "created": "2026-05-13T10:30:00+00:00", "type": "explicit", "member_id": "01JRVX6GG4XMSM55XBC3E518E0", "scale": "graded", "corpus_id": "01JRVX6GG4XMSM55XBC3E518DZ", "judgment_stats": { "count": 1500, "min_grade": 0, "max_grade": 4 } } } } }, "404": { "description": "Not Found", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/judgmentlists": { "get": { "tags": [ "Judgment Lists" ], "summary": "List Judgment Lists", "description": "Lists the Judgment Lists", "operationId": "list-judgment-lists", "parameters": [ { "name": "endpoint_type", "in": "query", "description": "The endpoint types to filter judgment lists by", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EndpointType" } } } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ListJudgmentListsResponse" }, "example": { "judgment_lists": [ { "id": "01JRVX6GG4XMSM55XBC3E518DY", "name": "Movies judgments", "created": "2026-05-13T10:30:00+00:00", "type": "explicit", "member_id": "01JRVX6GG4XMSM55XBC3E518E0", "scale": "graded", "corpus_id": "01JRVX6GG4XMSM55XBC3E518DZ", "judgment_stats": { "count": 1500, "min_grade": 0, "max_grade": 4 } }, { "id": "01JRVX6GG4XMSM55XBC3E518E3", "name": "Books judgments", "created": "2026-05-10T09:00:00+00:00", "type": "golden", "member_id": "01JRVX6GG4XMSM55XBC3E518E0", "scale": "binary", "corpus_id": "01JRVX6GG4XMSM55XBC3E518E4", "judgment_stats": { "count": 800, "min_grade": 0, "max_grade": 1 } } ] } }, "application/json": { "schema": { "$ref": "#/components/schemas/ListJudgmentListsResponse" }, "example": { "judgment_lists": [ { "id": "01JRVX6GG4XMSM55XBC3E518DY", "name": "Movies judgments", "created": "2026-05-13T10:30:00+00:00", "type": "explicit", "member_id": "01JRVX6GG4XMSM55XBC3E518E0", "scale": "graded", "corpus_id": "01JRVX6GG4XMSM55XBC3E518DZ", "judgment_stats": { "count": 1500, "min_grade": 0, "max_grade": 4 } }, { "id": "01JRVX6GG4XMSM55XBC3E518E3", "name": "Books judgments", "created": "2026-05-10T09:00:00+00:00", "type": "golden", "member_id": "01JRVX6GG4XMSM55XBC3E518E0", "scale": "binary", "corpus_id": "01JRVX6GG4XMSM55XBC3E518E4", "judgment_stats": { "count": 800, "min_grade": 0, "max_grade": 1 } } ] } }, "text/json": { "schema": { "$ref": "#/components/schemas/ListJudgmentListsResponse" }, "example": { "judgment_lists": [ { "id": "01JRVX6GG4XMSM55XBC3E518DY", "name": "Movies judgments", "created": "2026-05-13T10:30:00+00:00", "type": "explicit", "member_id": "01JRVX6GG4XMSM55XBC3E518E0", "scale": "graded", "corpus_id": "01JRVX6GG4XMSM55XBC3E518DZ", "judgment_stats": { "count": 1500, "min_grade": 0, "max_grade": 4 } }, { "id": "01JRVX6GG4XMSM55XBC3E518E3", "name": "Books judgments", "created": "2026-05-10T09:00:00+00:00", "type": "golden", "member_id": "01JRVX6GG4XMSM55XBC3E518E0", "scale": "binary", "corpus_id": "01JRVX6GG4XMSM55XBC3E518E4", "judgment_stats": { "count": 800, "min_grade": 0, "max_grade": 1 } } ] } } } } }, "security": [ { "Bearer": [] } ] }, "delete": { "tags": [ "Judgment Lists" ], "summary": "Delete Judgment Lists", "description": "Deletes the Judgment Lists with the given IDs.", "operationId": "delete-judgment-lists", "parameters": [ { "name": "judgment_list_id", "in": "query", "description": "The unique identifiers of the judgment lists to delete.", "required": true, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "OK" }, "404": { "description": "Not Found", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/judgments": { "get": { "tags": [ "Judgments" ], "summary": "List judgments", "description": "Gets judgments for a query within a corpus, identified by corpus ID and query object hash (OId).\n For admins, returns all members' judgments with member info. For non-admins, returns only their own judgments plus AI judgments.", "operationId": "list-judgments", "parameters": [ { "name": "corpus_id", "in": "query", "description": "The unique identifier of the corpus.", "schema": { "type": "string" } }, { "name": "oid", "in": "query", "description": "The query object hash (OId).", "schema": { "type": "string" } }, { "name": "evaluation_query_id", "in": "query", "description": "Optional: filter to judgments linked to a specific evaluation query.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListJudgmentsResponse" }, "example": { "judgments": [ { "candidate_id": "tt0111161", "grade": 4, "member_id": "01JRVX6GG4XMSM55XBC3E518E0", "user_name": "alice" }, { "candidate_id": "tt0068646", "grade": 3, "ai_judge_id": "01JRVX6GG4XMSM55XBC3E518E1", "ai_judge_name": "Claude Judge", "reasoning": "The candidate's title and overview closely match the query intent." } ] } } } } }, "security": [ { "Bearer": [] } ] }, "post": { "tags": [ "Judgments" ], "summary": "Upsert judgments", "description": "Creates or updates the authenticated member's judgments. Judgments are scoped to a corpus\n and identified by query content hash + candidate ID.", "operationId": "upsert-judgments", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertJudgmentsRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/UpsertJudgmentsRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertJudgmentsResponse" }, "example": { "judgments": [ { "query_id": "01JRVX6GG4XMSM55XBC3E518E2", "grade": 4, "created": "2026-05-13T10:30:00+00:00", "member_id": "01JRVX6GG4XMSM55XBC3E518E0", "candidate_id": "tt0126029" }, { "grade": 3, "created": "2026-05-13T10:31:00+00:00", "updated": "2026-05-13T11:15:00+00:00", "candidate_id": "tt0068646", "ai_judge_id": "01JRVX6GG4XMSM55XBC3E518E1", "reasoning": "The candidate's title and overview closely match the query intent." } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/license": { "get": { "tags": [ "License" ], "summary": "Get current license information.", "description": "Returns information about the current license including tier, expiration, and limits.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LicenseInfoResponse" }, "example": { "is_valid": true, "is_expired": false, "is_fallback": false, "tier": "team", "type": "standard", "licensee": { "name": "Acme Corporation", "email": "licensing@acme.com" }, "expires_at": "2026-12-31T23:59:59+00:00", "limits": { "max_members": 10, "max_app_clients": 10 } } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/license/limits": { "get": { "tags": [ "License" ], "summary": "Get current resource usage and limits.", "description": "Returns the current usage count and limits for all resource types.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceLimitsResponse" }, "example": { "members": { "current": 5, "max": 25, "limit_reached": false, "percent_used": 20 }, "endpoints": { "current": 3, "max": 25, "limit_reached": false, "percent_used": 12 }, "query_sets": { "current": 12, "limit_reached": false }, "query_templates": { "current": 8, "limit_reached": false }, "evaluations": { "current": 42, "limit_reached": false }, "judgment_lists": { "current": 6, "limit_reached": false }, "app_clients": { "current": 2, "max": 10, "limit_reached": false, "percent_used": 20 } } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/members": { "get": { "tags": [ "Members" ], "summary": "List Members", "description": "List all members in the system.", "operationId": "list-members", "parameters": [ { "name": "page", "in": "query", "description": "The page number (1-based).", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "default": 1 } }, { "name": "page_size", "in": "query", "description": "The number of items per page.", "schema": { "maximum": 100, "minimum": 10, "type": "integer", "format": "int32", "default": 25 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListMembersResponse" }, "example": { "members": [ { "picture": "https://www.gravatar.com/avatar/5658ffccee7f0ebfda2b226238b1eb6e", "name": "Example Member", "username": "member@example.com", "id": "01JRVX6GG4XMSM55XBC3E518DY", "roles": [ "Admin" ], "status": "active" } ], "page": 1, "page_size": 20, "total_count": 1, "total_pages": 1 } } } } }, "security": [ { "Bearer": [] } ] }, "delete": { "tags": [ "Members" ], "summary": "Archive Members", "description": "Archives the members by their given unique identifier.", "operationId": "archive-member", "parameters": [ { "name": "member_id", "in": "query", "description": "The unique identifiers of the members to archive.", "required": true, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/members/{member_id}": { "get": { "tags": [ "Members" ], "summary": "Get Member", "description": "Gets a member by their given unique identifier.", "operationId": "get-member", "parameters": [ { "name": "member_id", "in": "path", "description": "The unique identifier of the member.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/members/{member_id}/restore": { "put": { "tags": [ "Members" ], "summary": "Restore Member", "description": "Restores an archived member by their given unique identifier.", "operationId": "restore-member", "parameters": [ { "name": "member_id", "in": "path", "description": "The unique identifier of the member.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": {} } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/members/invite": { "post": { "tags": [ "Members" ], "summary": "Invite Member", "description": "Invites a new member by email. The member will receive an invitation email with a link to set their password.", "operationId": "invite-member", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteMemberRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/InviteMemberRequest" } } }, "required": true }, "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/members/{member_id}/resend-invitation": { "post": { "tags": [ "Members" ], "summary": "Resend Invitation", "description": "Resends the invitation email for a member who has not yet accepted their invitation.", "operationId": "resend-invitation", "parameters": [ { "name": "member_id", "in": "path", "description": "The unique identifier of the member.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } } } }, "404": { "description": "Not Found", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/metrics": { "get": { "tags": [ "Evaluation Runs" ], "summary": "List Metrics", "description": "List the ranking metrics available for evaluation runs.", "operationId": "list-metrics", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListMetricsResponse" }, "example": { "metrics": [ { "name": "P@k", "description": "Precision at K", "default_k": 10 }, { "name": "R@k", "description": "Recall at K", "default_k": 10 }, { "name": "F1@k", "description": "F1 Score at K. The F-Score balances precision and recall using a harmonic mean.", "default_k": 10 }, { "name": "MAP", "description": "Mean Average Precision computes the mean of the Average Precision across multiple queries and their results." }, { "name": "ERR@k", "description": "Expected Reciprocal Rank at k", "default_k": 10 }, { "name": "MRR@k", "description": "Mean Reciprocal Rank measures how early the first relevant result appears in a ranked list.", "default_k": 10 }, { "name": "DCG@k", "description": "Discounted Cumulative Gain measures the gain of the top K results whilst also considering the rank/position of results in the ranked list", "default_k": 10 }, { "name": "NDCG@k", "description": "Normalized Discounted Cumulative Gain measures the gain of the top K results whilst also considering the rank/position of results in the ranked list, normalized by the ideal gain", "default_k": 10 }, { "name": "Best@k", "description": "Best relevance grade within top K results", "default_k": 10 } ] } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/query-sets/upload": { "post": { "tags": [ "Query Sets" ], "summary": "Upload Query Set", "description": "Creates a new Query Set by uploading a file of queries.", "operationId": "upload-query-set", "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "queries": { "$ref": "#/components/schemas/IFormFile" } } } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuerySetResponse" }, "example": { "id": "01JRW0C6HBJXTJKXZP6CZDNPZT", "name": "Movies", "description": "Movies from TMDB", "created": "2025-04-01T00:00:00+00:00", "queries": [ { "query": { "query": "Shrek" }, "qid": "12345", "oid": "67890" }, { "query": { "query": "The Godfather" }, "qid": "12346", "oid": "67891" }, { "query": { "query": "Forrest Gump" }, "qid": "12347", "oid": "67892" }, { "query": { "query": "The Matrix" }, "qid": "12348", "oid": "67893" }, { "query": { "query": "The Shawshank Redemption" }, "qid": "12349", "oid": "67894" } ], "format": "json" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.3", "title": "Forbidden.", "status": 403 } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/query-sets": { "post": { "tags": [ "Query Sets" ], "summary": "Create Query Set", "description": "Creates a new query set.", "operationId": "create-query-set", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateQuerySetRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CreateQuerySetRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuerySetResponse" }, "example": { "id": "01JRW0C6HBJXTJKXZP6CZDNPZT", "name": "Movies", "description": "Movies from TMDB", "created": "2025-04-01T00:00:00+00:00", "queries": [ { "query": { "query": "Shrek" }, "qid": "12345", "oid": "67890" }, { "query": { "query": "The Godfather" }, "qid": "12346", "oid": "67891" }, { "query": { "query": "Forrest Gump" }, "qid": "12347", "oid": "67892" }, { "query": { "query": "The Matrix" }, "qid": "12348", "oid": "67893" }, { "query": { "query": "The Shawshank Redemption" }, "qid": "12349", "oid": "67894" } ], "format": "json" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.3", "title": "Forbidden.", "status": 403 } } } } }, "security": [ { "Bearer": [] } ] }, "get": { "tags": [ "Query Sets" ], "summary": "List Query Sets", "description": "Lists the Query Sets", "operationId": "list-query-sets", "parameters": [ { "name": "queries", "in": "query", "description": "Whether to include queries in the response.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListQuerySetsResponse" }, "example": { "query_sets": [ { "id": "01JRVX6GG4XMSM55XBC3E518DY", "name": "Movies", "description": "Movies from TMDB", "member_id": "01JRVX6GG4XMSM55XBC3E518E2", "created": "2026-05-13T10:30:00+00:00", "format": "json" }, { "id": "01JRVX6GG4XMSM55XBC3E518F4", "name": "Music", "description": "Music tracks from MusicBrainz", "member_id": "01JRVX6GG4XMSM55XBC3E518E2", "created": "2026-05-14T11:00:00+00:00", "format": "json" } ] } } } } }, "security": [ { "Bearer": [] } ] }, "delete": { "tags": [ "Query Sets" ], "summary": "Delete Query Sets", "description": "Deletes the Query Sets given by the uniques identifiers.", "operationId": "delete-query-sets", "parameters": [ { "name": "query_set_id", "in": "query", "description": "The unique identifiers of the query sets to delete.", "required": true, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "OK" } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/query-sets/ids": { "post": { "tags": [ "Query Sets" ], "summary": "Create Query Ids", "description": "Creates the Query Ids for a set of queries. Query Ids are hashes of the query that can be used to uniquely\n identify a query text or query JSON object.", "operationId": "create-query-ids", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateQueryIdsRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CreateQueryIdsRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CreateQueryIdsRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateQueryIdsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/query-sets/{query_set_id}": { "get": { "tags": [ "Query Sets" ], "summary": "Get Query Set", "description": "Gets a Query Set by its unique identifier", "operationId": "get-query-set", "parameters": [ { "name": "query_set_id", "in": "path", "description": "The unique identifier of the query set.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuerySetResponse" }, "example": { "id": "01JRW0C6HBJXTJKXZP6CZDNPZT", "name": "Movies", "description": "Movies from TMDB", "created": "2025-04-01T00:00:00+00:00", "queries": [ { "query": { "query": "Shrek" }, "qid": "12345", "oid": "67890" }, { "query": { "query": "The Godfather" }, "qid": "12346", "oid": "67891" }, { "query": { "query": "Forrest Gump" }, "qid": "12347", "oid": "67892" }, { "query": { "query": "The Matrix" }, "qid": "12348", "oid": "67893" }, { "query": { "query": "The Shawshank Redemption" }, "qid": "12349", "oid": "67894" } ], "format": "json" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/query-templates": { "post": { "tags": [ "Query Templates" ], "summary": "Create Query Template", "description": "Creates a new query template.\n \n Query templates are [Mustache](https://mustache.github.io/) / [Handlebars](https://handlebarsjs.com/) templates\n that generate dynamic HTTP request bodies and query strings. These templates support variable substitution,\n conditional logic, and iteration, allowing for flexible request construction.\n \n A query template can be used in conjunction with a query set to generate a collection of search requests to execute against\n a search endpoint. Each search request is created by applying each query in a query set to the query template,\n producing fully-formed search requests tailored to specific input data.\n \n This allows for dynamic and reusable query definitions, enabling efficient execution of parameterized search\n requests across different datasets.", "operationId": "create-query-template", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateQueryTemplateRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CreateQueryTemplateRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryTemplateResponse" }, "example": { "id": "01JRW1AXDZY6Z2QHSBK5EVKYHN", "content_type": "json", "body": "{ \"query\": { \"match\": { \"title\": \"{{query}}\" } } }", "query_string": "?size={{size}}", "name": "match_title", "created": "2025-04-01T00:00:00+00:00" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.3", "title": "Forbidden.", "status": 403 } } } } }, "security": [ { "Bearer": [] } ] }, "get": { "tags": [ "Query Templates" ], "summary": "List Query Templates", "description": "Lists the query templates available.\n \n Query templates are [Mustache](https://mustache.github.io/) / [Handlebars](https://handlebarsjs.com/) templates\n that generate dynamic HTTP request bodies and query strings. These templates support variable substitution,\n conditional logic, and iteration, allowing for flexible request construction.\n \n A query template can be used in conjunction with a query set to generate a collection of search requests to execute against\n a search endpoint. Each search request is created by applying each query in a query set to the query template,\n producing fully-formed search requests tailored to specific input data.\n \n This allows for dynamic and reusable query definitions, enabling efficient execution of parameterized search\n requests across different datasets.", "operationId": "list-query-templates", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListQueryTemplatesResponse" }, "example": { "query_templates": [ { "id": "01JRVX6GG4XMSM55XBC3E518DY", "content_type": "json", "body": "{ \"query\": { \"match\": { \"title\": \"{{query}}\" } } }", "query_string": "?size={{size}}", "name": "Multi-match query", "member_id": "01JRVX6GG4XMSM55XBC3E518E2", "created": "2026-05-13T10:30:00+00:00" } ] } } } } }, "security": [ { "Bearer": [] } ] }, "delete": { "tags": [ "Query Templates" ], "summary": "Delete Query Templates", "description": "Deletes the Query Templates given by the unique identifiers.", "operationId": "delete-query-templates", "parameters": [ { "name": "query_template_id", "in": "query", "description": "The unique identifiers of the query templates to delete.", "required": true, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "OK" } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/query-templates/{query_template_id}": { "put": { "tags": [ "Query Templates" ], "summary": "Update Query Template", "description": "Updates an existing Query Template.\n \n Query templates are [Mustache](https://mustache.github.io/) / [Handlebars](https://handlebarsjs.com/) templates\n that generate dynamic HTTP request bodies and query strings. These templates support variable substitution,\n conditional logic, and iteration, allowing for flexible request construction.\n \n A query template can be used in conjunction with a query set to generate a collection of search requests to execute against\n a search endpoint. Each search request is created by applying each query in a query set to the query template,\n producing fully-formed search requests tailored to specific input data.\n \n This allows for dynamic and reusable query definitions, enabling efficient execution of parameterized search\n requests across different datasets.", "operationId": "update-query-template", "parameters": [ { "name": "query_template_id", "in": "path", "description": "The unique identifier of the query template.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateQueryTemplateRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/UpdateQueryTemplateRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryTemplateResponse" }, "example": { "id": "01JRW1AXDZY6Z2QHSBK5EVKYHN", "content_type": "json", "body": "{ \"query\": { \"match\": { \"title\": \"{{query}}\" } } }", "query_string": "?size={{size}}", "name": "match_title", "created": "2025-04-01T00:00:00+00:00" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } } }, "security": [ { "Bearer": [] } ] }, "get": { "tags": [ "Query Templates" ], "summary": "Get Query Template", "description": "Gets the Query Template by ID.", "operationId": "get-query-template", "parameters": [ { "name": "query_template_id", "in": "path", "description": "The unique identifier of the query template.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryTemplateResponse" }, "example": { "id": "01JRW1AXDZY6Z2QHSBK5EVKYHN", "content_type": "json", "body": "{ \"query\": { \"match\": { \"title\": \"{{query}}\" } } }", "query_string": "?size={{size}}", "name": "match_title", "created": "2025-04-01T00:00:00+00:00" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/query-templates/test/{query_set_id}": { "post": { "tags": [ "Query Templates" ], "summary": "Test Query Template with Query Set", "description": "Tests a Query Template by using it to render an existing Query Set.", "operationId": "test-query-template-query-set", "parameters": [ { "name": "query_set_id", "in": "path", "description": "The unique identifier of the query set. Only the first five queries are rendered.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestQueryTemplateRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/TestQueryTemplateRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListQueryTemplatesTestResponse" }, "example": { "query_templates": [ { "query": "Shrek", "query_string": "?size=10", "body": "{ \"query\": { \"match\": { \"title\": \"Shrek\" } } }" } ], "format": "json" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/query-templates/test": { "post": { "tags": [ "Query Templates" ], "summary": "Test Query Template", "description": "Tests a Query Template by using it to render a collection of provided queries.", "operationId": "test-query-template", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestQueryTemplateWithQueriesRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/TestQueryTemplateWithQueriesRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListQueryTemplatesTestResponse" }, "example": { "query_templates": [ { "query": "Shrek", "query_string": "?size=10", "body": "{ \"query\": { \"match\": { \"title\": \"Shrek\" } } }" } ], "format": "json" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found.", "status": 404 } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/ubi/track-event": { "post": { "tags": [ "User Behavior Insights" ], "summary": "Track Events", "description": "Tracks one or more events, typically in response to user actions.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackEventsRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/TrackEventsRequest" } } }, "required": true }, "responses": { "204": { "description": "No Content", "content": { "application/json": {} } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } } } } } } }, "/api/v1/ubi/track-query": { "post": { "tags": [ "User Behavior Insights" ], "summary": "Track Query", "description": "Tracks a query to a search engine/API.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackQueryRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/TrackQueryRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackQueryResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/ubi/query": { "post": { "tags": [ "User Behavior Insights" ], "summary": "Query User Behavior Insights Data", "description": "Query data collected from User Behavior Insights", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/QueryRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryResponse" }, "example": { "meta": [ { "name": "action_name", "type": "String" }, { "name": "timestamp", "type": "DateTime64(3, 'UTC')" } ], "data": [ { "action_name": "click", "timestamp": "2026-05-13T10:30:00.000Z" }, { "action_name": "add_to_basket", "timestamp": "2026-05-13T10:31:12.000Z" } ], "rows": 1500, "statistics": { "bytes_read": 204800, "elapsed": 0.042, "rows_read": 1500 } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } } } } }, "security": [ { "Bearer": [] } ] } } }, "components": { "schemas": { "AcknowledgedResponse": { "required": [ "message" ], "type": "object", "properties": { "message": { "type": "string", "description": "An acknowledgment message.", "example": "Acknowledged" } } }, "AdHocQueryBaseline": { "required": [ "run_id", "run_name", "candidates" ], "type": "object", "properties": { "run_id": { "type": "string", "description": "The unique identifier of the baseline evaluation run.", "example": "01JRVX6GG4XMSM55XBC3E518E1" }, "run_name": { "type": "string", "description": "The name of the baseline evaluation run.", "example": "Baseline run" }, "total_candidates": { "type": "integer", "description": "The total number of candidates in the baseline run for this query.", "format": "int64", "example": 1024 }, "candidates": { "type": "array", "items": { "$ref": "#/components/schemas/Candidate" }, "description": "The candidates from the baseline run for comparison." } }, "description": "Baseline comparison data from the most recent completed/locked run, if available." }, "AdHocQueryExecution": { "required": [ "url", "method" ], "type": "object", "properties": { "url": { "type": "string", "description": "The url of the request executed against the endpoint.", "example": "https://localhost:9200/movies/_search" }, "method": { "type": "string", "description": "The HTTP method used for the request.", "example": "GET" }, "body": { "type": [ "null", "string" ], "description": "The request body sent to the endpoint.", "example": { "query": { "match": { "title": "Shrek" } } } }, "content_type": { "type": [ "null", "string" ], "description": "The content type of the request body.", "example": "application/json" }, "headers": { "type": [ "null", "object" ], "additionalProperties": { "type": "string" }, "description": "The HTTP headers sent with the request.", "example": { "Content-Type": "application/json" } } }, "description": "Details about the executed request." }, "AdHocQueryRequest": { "required": [ "query" ], "type": "object", "properties": { "query": { "$ref": "#/components/schemas/Query" }, "query_item_id": { "type": [ "null", "string" ], "description": "Optional query item ID to enable baseline lookup.", "example": "01JRVX6GG4XMSM55XBC3E518E0" }, "body": { "type": [ "null", "string" ], "description": "Optional body template override. If not specified, uses the evaluation's query template body.", "example": { "query": { "match": { "title": "{{query}}" } } } }, "query_string": { "type": [ "null", "string" ], "description": "Optional query string template override. If not specified, uses the evaluation's query template query string.", "example": "?size=10" }, "content_type": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/QueryTemplateContentType" } ] }, "headers": { "type": [ "null", "object" ], "additionalProperties": { "type": "string" }, "description": "Optional headers override.", "example": { "Content-Type": "application/json" } } }, "example": { "query": { "query": "Shrek" }, "query_item_id": "01JRVX6GG4XMSM55XBC3E518E0", "body": "{ \"query\": { \"match\": { \"title\": \"{{query}}\" } } }", "query_string": "?size=10", "content_type": "json", "headers": { "Content-Type": "application/json" } } }, "AdHocQueryResponse": { "required": [ "execution", "result" ], "type": "object", "properties": { "execution": { "description": "Details about the executed request.", "$ref": "#/components/schemas/AdHocQueryExecution" }, "result": { "description": "The result of executing the query.", "$ref": "#/components/schemas/AdHocQueryResultResponse" }, "baseline": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AdHocQueryBaseline" } ] }, "judgments": { "type": [ "null", "object" ], "additionalProperties": { "type": "object", "additionalProperties": { "type": "integer", "format": "int32" } }, "description": "Existing judgments grouped by scale, then keyed by candidate_id to grade." }, "qid": { "type": [ "null", "string" ], "description": "The computed QId for the query.", "example": 12345 }, "oid": { "type": [ "null", "string" ], "description": "The computed OId for the query.", "example": 67890 } }, "example": { "execution": { "url": "https://localhost:9200/movies/_search", "method": "GET", "body": "{ \"query\": { \"match\": { \"title\": \"Shrek\" } } }", "content_type": "application/json", "headers": { "Content-Type": "application/json" } }, "result": { "status_code": 200, "failed": false, "total_candidates": 1024, "candidates": [ { "id": "tt0126029", "title": "Shrek" } ] }, "baseline": { "run_id": "01JRVX6GG4XMSM55XBC3E518E1", "run_name": "Baseline run", "total_candidates": 1024, "candidates": [ { "id": "tt0126029", "title": "Shrek" } ] }, "judgments": { "graded": { "tt0126029": 4 } }, "qid": "12345", "oid": "67890" } }, "AdHocQueryResultResponse": { "required": [ "status_code", "failed", "candidates" ], "type": "object", "properties": { "status_code": { "type": "integer", "description": "The HTTP status code returned by the endpoint.", "format": "int32", "example": 200 }, "failed": { "type": "boolean", "description": "Whether the request failed.", "example": false }, "message": { "type": [ "null", "string" ], "description": "A failure message, if the request failed.", "example": "Request timed out" }, "total_candidates": { "type": "integer", "description": "The total number of candidates reported by the endpoint.", "format": "int64", "example": 1024 }, "candidates": { "type": "array", "items": { "$ref": "#/components/schemas/Candidate" }, "description": "The candidates returned by the endpoint after mapping." } }, "description": "The result of executing the query." }, "AiJudgeResponse": { "required": [ "id", "name", "ai_provider_id", "ai_provider_type", "ai_provider_name", "model", "prompt_template", "created" ], "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the AI judge.", "example": "01JRVX6GG4XMSM55XBC3E518DY" }, "name": { "type": "string", "description": "The judge's display name.", "example": "Relevance Judge" }, "description": { "type": [ "null", "string" ], "description": "An optional description for the judge.", "example": "Judges relevance of movie search results on a 0-4 scale." }, "ai_provider_id": { "type": "string", "description": "The unique identifier of the AI provider this judge invokes.", "example": "01JRVX6GG4XMSM55XBC3E518E0" }, "ai_provider_type": { "description": "The provider type, denormalised from the linked provider for filtering and display.", "$ref": "#/components/schemas/AiProviderType" }, "ai_provider_name": { "type": "string", "description": "The provider's display name, denormalised for UI rendering.", "example": "OpenAI Production" }, "model": { "type": "string", "description": "The model identifier passed to the provider, e.g. \"gpt-4o\".", "example": "gpt-4o" }, "prompt_template": { "type": "string", "description": "The Handlebars prompt template the judge sends to the model.", "example": "Rate the relevance of the result {{candidate.title}} for the query \"{{query}}\" on a scale of 0-4." }, "max_concurrency": { "type": "integer", "description": "Maximum number of concurrent LLM requests during a judging run.", "format": "int32", "example": 5 }, "batch_size": { "type": [ "null", "integer" ], "description": "Number of candidates per prompt. null or 1 means one candidate per LLM call.\n Values greater than 1 batch multiple candidates for the same query into a single prompt.", "format": "int32", "example": 5 }, "include_images": { "type": "boolean", "description": "Whether candidate images are included in the prompt. Requires a vision-capable model.", "example": false }, "member_id": { "type": [ "null", "string" ], "description": "The owning member's identifier, or null if the judge is shared across the workspace.", "example": "01JRVX6GG4XMSM55XBC3E518E1" }, "created": { "type": "string", "description": "The UTC timestamp at which the judge was created.", "format": "date-time", "example": "2026-05-10T09:00:00Z" }, "updated": { "type": [ "null", "string" ], "description": "The UTC timestamp at which the judge was last updated, or null if it has never been updated.", "format": "date-time", "example": "2026-05-13T10:30:00Z" } } }, "AiJudgingRunResponse": { "required": [ "id", "ai_judge_provider_type", "status", "created" ], "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the AI judging run.", "example": "01JRVX6GG4XMSM55XBC3E518DY" }, "evaluation_run_id": { "type": [ "null", "string" ], "description": "The identifier of the evaluation run this judging run is associated with.", "example": "01JRVX6GG4XMSM55XBC3E518E2" }, "ai_judge_id": { "type": [ "null", "string" ], "description": "The identifier of the AI judge used for this run.", "example": "01JRVX6GG4XMSM55XBC3E518E3" }, "ai_judge_name": { "type": [ "null", "string" ], "description": "The display name of the AI judge used for this run.", "example": "Relevance Judge" }, "ai_judge_provider_type": { "description": "The provider type, denormalised from the linked provider for filtering and display.", "$ref": "#/components/schemas/AiProviderType" }, "status": { "description": "The current status of the judging run.", "$ref": "#/components/schemas/AiJudgingRunStatus" }, "progress": { "type": "number", "description": "The fraction of the run completed, between 0 and 1.", "format": "double", "example": 0.75 }, "total_count": { "type": "integer", "description": "The total number of candidate judgments to produce.", "format": "int32", "example": 200 }, "completed_count": { "type": "integer", "description": "The number of candidate judgments produced so far.", "format": "int32", "example": 150 }, "failed_count": { "type": "integer", "description": "The number of candidate judgments that failed.", "format": "int32", "example": 2 }, "input_token_count": { "type": "integer", "description": "The total number of input tokens consumed by the run.", "format": "int64", "example": 125000 }, "output_token_count": { "type": "integer", "description": "The total number of output tokens produced by the run.", "format": "int64", "example": 45000 }, "error_message": { "type": [ "null", "string" ], "description": "The error message if the run failed, otherwise null.", "example": "Provider returned 429 Too Many Requests" }, "initiated_by_member_id": { "type": [ "null", "string" ], "description": "The identifier of the member who initiated the run.", "example": "01JRVX6GG4XMSM55XBC3E518E4" }, "created": { "type": "string", "description": "The UTC timestamp at which the run was created.", "format": "date-time", "example": "2026-05-13T10:30:00Z" }, "updated": { "type": [ "null", "string" ], "description": "The UTC timestamp at which the run was last updated.", "format": "date-time", "example": "2026-05-13T10:45:00Z" }, "completed": { "type": [ "null", "string" ], "description": "The UTC timestamp at which the run completed.", "format": "date-time", "example": "2026-05-13T11:15:00Z" } } }, "AiJudgingRunStatus": { "enum": [ "pending", "queued", "running", "completed", "failed", "cancelled" ], "description": "The current status of the judging run.", "example": "running" }, "AiProviderResponse": { "required": [ "type" ], "type": "object", "anyOf": [ { "$ref": "#/components/schemas/AiProviderResponseOpenAiProviderResponse" }, { "$ref": "#/components/schemas/AiProviderResponseAnthropicProviderResponse" }, { "$ref": "#/components/schemas/AiProviderResponseAzureOpenAiProviderResponse" }, { "$ref": "#/components/schemas/AiProviderResponseOllamaProviderResponse" }, { "$ref": "#/components/schemas/AiProviderResponseCustomProviderResponse" }, { "$ref": "#/components/schemas/AiProviderResponseAmazonBedrockProviderResponse" } ], "description": "AI provider read shape. Secret fields are never returned. Non-secret fields are returned\n as-is. Provider type is the discriminator on the type property.", "discriminator": { "propertyName": "type", "mapping": { "openai": "#/components/schemas/AiProviderResponseOpenAiProviderResponse", "anthropic": "#/components/schemas/AiProviderResponseAnthropicProviderResponse", "azure_openai": "#/components/schemas/AiProviderResponseAzureOpenAiProviderResponse", "ollama": "#/components/schemas/AiProviderResponseOllamaProviderResponse", "custom": "#/components/schemas/AiProviderResponseCustomProviderResponse", "amazon_bedrock": "#/components/schemas/AiProviderResponseAmazonBedrockProviderResponse" } } }, "AiProviderResponseAmazonBedrockProviderResponse": { "required": [ "aws_region", "access_key_id", "id", "name", "created" ], "properties": { "type": { "enum": [ "amazon_bedrock" ], "type": "string" }, "aws_region": { "type": "string", "description": "The AWS region in which Bedrock is provisioned.", "example": "us-east-1" }, "access_key_id": { "type": "string", "description": "The AWS access key ID. The matching secret access key is never returned.", "example": "AKIAIOSFODNN7EXAMPLE" }, "id": { "type": "string", "description": "The unique identifier of the AI provider.", "example": "01JRVX6GG4XMSM55XBC3E518DY" }, "name": { "type": "string", "description": "The provider's display name.", "example": "OpenAI Production" }, "member_id": { "type": [ "null", "string" ], "description": "The owning member's identifier, or null if the provider is shared across the workspace.", "example": "01JRVX6GG4XMSM55XBC3E518E0" }, "created": { "type": "string", "description": "The UTC timestamp at which the provider was created.", "format": "date-time", "example": "2026-05-10T09:00:00Z" }, "updated": { "type": [ "null", "string" ], "description": "The UTC timestamp at which the provider was last updated, or null if it has never been updated.", "format": "date-time", "example": "2026-05-13T10:30:00Z" } }, "description": "Read shape for an Amazon Bedrock provider. The AWS secret access key is never returned." }, "AiProviderResponseAnthropicProviderResponse": { "required": [ "id", "name", "created" ], "properties": { "type": { "enum": [ "anthropic" ], "type": "string" }, "id": { "type": "string", "description": "The unique identifier of the AI provider.", "example": "01JRVX6GG4XMSM55XBC3E518DY" }, "name": { "type": "string", "description": "The provider's display name.", "example": "OpenAI Production" }, "member_id": { "type": [ "null", "string" ], "description": "The owning member's identifier, or null if the provider is shared across the workspace.", "example": "01JRVX6GG4XMSM55XBC3E518E0" }, "created": { "type": "string", "description": "The UTC timestamp at which the provider was created.", "format": "date-time", "example": "2026-05-10T09:00:00Z" }, "updated": { "type": [ "null", "string" ], "description": "The UTC timestamp at which the provider was last updated, or null if it has never been updated.", "format": "date-time", "example": "2026-05-13T10:30:00Z" } }, "description": "Read shape for an Anthropic provider." }, "AiProviderResponseAzureOpenAiProviderResponse": { "required": [ "endpoint_url", "id", "name", "created" ], "properties": { "type": { "enum": [ "azure_openai" ], "type": "string" }, "endpoint_url": { "type": "string", "description": "The Azure OpenAI resource endpoint URL.", "example": "https://my-resource.openai.azure.com/" }, "id": { "type": "string", "description": "The unique identifier of the AI provider.", "example": "01JRVX6GG4XMSM55XBC3E518DY" }, "name": { "type": "string", "description": "The provider's display name.", "example": "OpenAI Production" }, "member_id": { "type": [ "null", "string" ], "description": "The owning member's identifier, or null if the provider is shared across the workspace.", "example": "01JRVX6GG4XMSM55XBC3E518E0" }, "created": { "type": "string", "description": "The UTC timestamp at which the provider was created.", "format": "date-time", "example": "2026-05-10T09:00:00Z" }, "updated": { "type": [ "null", "string" ], "description": "The UTC timestamp at which the provider was last updated, or null if it has never been updated.", "format": "date-time", "example": "2026-05-13T10:30:00Z" } }, "description": "Read shape for an Azure OpenAI provider." }, "AiProviderResponseCustomProviderResponse": { "required": [ "endpoint_url", "id", "name", "created" ], "properties": { "type": { "enum": [ "custom" ], "type": "string" }, "endpoint_url": { "type": "string", "description": "The endpoint URL of the OpenAI-compatible API.", "example": "https://llm.internal.example.com/v1/" }, "has_api_key": { "type": "boolean", "description": "Whether an API key has been configured. The key itself is never returned.", "example": true }, "id": { "type": "string", "description": "The unique identifier of the AI provider.", "example": "01JRVX6GG4XMSM55XBC3E518DY" }, "name": { "type": "string", "description": "The provider's display name.", "example": "OpenAI Production" }, "member_id": { "type": [ "null", "string" ], "description": "The owning member's identifier, or null if the provider is shared across the workspace.", "example": "01JRVX6GG4XMSM55XBC3E518E0" }, "created": { "type": "string", "description": "The UTC timestamp at which the provider was created.", "format": "date-time", "example": "2026-05-10T09:00:00Z" }, "updated": { "type": [ "null", "string" ], "description": "The UTC timestamp at which the provider was last updated, or null if it has never been updated.", "format": "date-time", "example": "2026-05-13T10:30:00Z" } }, "description": "Read shape for a custom OpenAI-compatible provider." }, "AiProviderResponseOllamaProviderResponse": { "required": [ "endpoint_url", "id", "name", "created" ], "properties": { "type": { "enum": [ "ollama" ], "type": "string" }, "endpoint_url": { "type": "string", "description": "The Ollama server endpoint URL.", "example": "http://localhost:11434/" }, "id": { "type": "string", "description": "The unique identifier of the AI provider.", "example": "01JRVX6GG4XMSM55XBC3E518DY" }, "name": { "type": "string", "description": "The provider's display name.", "example": "OpenAI Production" }, "member_id": { "type": [ "null", "string" ], "description": "The owning member's identifier, or null if the provider is shared across the workspace.", "example": "01JRVX6GG4XMSM55XBC3E518E0" }, "created": { "type": "string", "description": "The UTC timestamp at which the provider was created.", "format": "date-time", "example": "2026-05-10T09:00:00Z" }, "updated": { "type": [ "null", "string" ], "description": "The UTC timestamp at which the provider was last updated, or null if it has never been updated.", "format": "date-time", "example": "2026-05-13T10:30:00Z" } }, "description": "Read shape for an Ollama provider." }, "AiProviderResponseOpenAiProviderResponse": { "required": [ "id", "name", "created" ], "properties": { "type": { "enum": [ "openai" ], "type": "string" }, "id": { "type": "string", "description": "The unique identifier of the AI provider.", "example": "01JRVX6GG4XMSM55XBC3E518DY" }, "name": { "type": "string", "description": "The provider's display name.", "example": "OpenAI Production" }, "member_id": { "type": [ "null", "string" ], "description": "The owning member's identifier, or null if the provider is shared across the workspace.", "example": "01JRVX6GG4XMSM55XBC3E518E0" }, "created": { "type": "string", "description": "The UTC timestamp at which the provider was created.", "format": "date-time", "example": "2026-05-10T09:00:00Z" }, "updated": { "type": [ "null", "string" ], "description": "The UTC timestamp at which the provider was last updated, or null if it has never been updated.", "format": "date-time", "example": "2026-05-13T10:30:00Z" } }, "description": "Read shape for an OpenAI provider." }, "AiProviderType": { "enum": [ "openai", "anthropic", "azure_openai", "ollama", "custom", "amazon_bedrock" ], "description": "The provider type, denormalised from the linked provider for filtering and display.", "example": "openai" }, "AnalysisMetricsResponse": { "required": [ "name", "statistics", "metrics" ], "type": "object", "properties": { "name": { "type": "string", "description": "The name of the query to which the metrics relate.", "example": "Shrek" }, "statistics": { "type": "array", "items": { "$ref": "#/components/schemas/MetricStatistics" }, "description": "The metric statistics" }, "metrics": { "type": "array", "items": { "$ref": "#/components/schemas/MetricBucket" }, "description": "The metrics" } }, "example": { "name": "Shrek", "statistics": [ { "name": "NDCG", "count": 100, "count_one": 25, "count_zero": 10, "mean": 0.75, "variance": 0.05, "standard_deviation": 0.22, "kurtosis": 2.5, "skewness": 0.1 } ], "metrics": [ { "name": "NDCG", "bucket_start": 0, "bucket_count": 10 }, { "name": "NDCG", "bucket_start": 0.5, "bucket_count": 25 }, { "name": "NDCG", "bucket_start": 1, "bucket_count": 65 } ] } }, "AnalysisResponse": { "required": [ "id", "name", "created", "executions_processed", "executions_count", "status" ], "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the analysis", "example": "01JRVX6GG4XMSM55XBC3E518DY" }, "name": { "type": "string", "description": "The name of the analysis", "example": "Search relevance baseline" }, "created": { "type": "string", "description": "The datetime of when the analysis was created.", "format": "date-time", "example": "2026-05-13T10:30:00Z" }, "executions_processed": { "type": "integer", "description": "The number of executions processed for the analysis.", "format": "int64", "example": 42 }, "executions_count": { "type": "integer", "description": "The total count of executions for the analysis.", "format": "int64", "example": 100 }, "status": { "type": "string", "description": "The status of the analysis", "example": "completed" } } }, "AnalysisStatusResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the analysis", "example": "01JRVX6GG4XMSM55XBC3E518DY" }, "executions_processed": { "type": "integer", "description": "The number of executions processed", "format": "int64", "example": 42 }, "executions_count": { "type": "integer", "description": "The total number of executions", "format": "int64", "example": 100 }, "status": { "type": "string", "description": "The status", "example": "completed" }, "created": { "type": "string", "description": "The datetime at which the analysis was created.", "format": "date-time", "example": "2026-05-13T10:30:00Z" } } }, "AppClientResponse": { "required": [ "id", "name", "description", "roles", "client_id", "client_secret_hint", "created" ], "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the app client", "example": "01JRVX6GG4XMSM55XBC3E518DY" }, "name": { "type": "string", "description": "The name of the app client", "example": "Search Indexer" }, "description": { "type": "string", "description": "A description for the app client", "example": "App client used by the indexing pipeline" }, "roles": { "type": "array", "items": { "type": "string" }, "description": "The roles assigned to the app client", "example": [ "Admin" ] }, "client_id": { "type": "string", "description": "The client ID of the app client used for OAuth 2.0 authentication", "example": "01JRVX6GG4XMSM55XBC3E518E0" }, "client_secret_hint": { "type": "string", "description": "A hint for the client secret used for OAuth 2.0 authentication, to help\n identify credentials.", "example": "...A1b2" }, "last_used": { "type": [ "null", "string" ], "description": "The datetime that the app client was last used to authenticate.", "format": "date-time", "example": "2026-05-13T10:30:00Z" }, "created": { "type": "string", "description": "The datetime that the app client was created.", "format": "date-time", "example": "2026-05-01T09:00:00Z" }, "updated": { "type": [ "null", "string" ], "description": "The datetime that the app client was updated.", "format": "date-time", "example": "2026-05-10T12:00:00Z" } } }, "AuthenticationCredentials": { "required": [ "type" ], "type": "object", "anyOf": [ { "$ref": "#/components/schemas/AuthenticationCredentialsBearerAuthenticationCredentials" }, { "$ref": "#/components/schemas/AuthenticationCredentialsBasicAuthenticationCredentials" }, { "$ref": "#/components/schemas/AuthenticationCredentialsCustomHeaderCredentials" }, { "$ref": "#/components/schemas/AuthenticationCredentialsAwsAuthenticationCredentials" } ], "description": "Authentication type and credentials for authenticating with an endpoint.", "discriminator": { "propertyName": "type", "mapping": { "bearer": "#/components/schemas/AuthenticationCredentialsBearerAuthenticationCredentials", "basic": "#/components/schemas/AuthenticationCredentialsBasicAuthenticationCredentials", "custom": "#/components/schemas/AuthenticationCredentialsCustomHeaderCredentials", "aws": "#/components/schemas/AuthenticationCredentialsAwsAuthenticationCredentials" } }, "example": { "type": "basic", "username": "myusername", "password": "Password1234!" } }, "AuthenticationCredentialsAwsAuthenticationCredentials": { "required": [ "access_key", "access_secret", "aws_region" ], "properties": { "type": { "enum": [ "aws" ], "type": "string" }, "access_key": { "type": "string", "description": "The access key." }, "access_secret": { "type": "string", "description": "The access secret." }, "aws_region": { "type": "string", "description": "A valid AWS region", "example": "us-east-1" } }, "description": "Credentials for authenticating with an AWS service such as\n OpenSearch service, using AWS Sigv4.", "example": { "access_key": "AKIAIOSFODNN7EXAMPLE", "access_secret": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY", "aws_region": "us-east-1" } }, "AuthenticationCredentialsBasicAuthenticationCredentials": { "required": [ "username", "password" ], "properties": { "type": { "enum": [ "basic" ], "type": "string" }, "username": { "type": "string", "description": "The username", "example": "username" }, "password": { "type": "string", "description": "The password", "example": "Password1234!" } }, "example": { "username": "myusername", "password": "Password1234!" } }, "AuthenticationCredentialsBearerAuthenticationCredentials": { "required": [ "token" ], "properties": { "type": { "enum": [ "bearer" ], "type": "string" }, "token": { "type": "string" } }, "example": { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" } }, "AuthenticationCredentialsCustomHeaderCredentials": { "required": [ "header", "value" ], "properties": { "type": { "enum": [ "custom" ], "type": "string" }, "header": { "type": "string", "description": "The HTTP header name", "example": "X-ApiKey" }, "value": { "type": "string", "description": "The HTTP header value", "example": "Secret!" } }, "example": { "header": "X-Api-Key", "value": "inip2rn30923rjfnw2o0fwe" } }, "AuthenticationType": { "enum": [ "none", "basic", "bearer", "custom", "aws" ], "description": "The authentication type for the endpoint.", "example": "basic" }, "AuthenticationUrlResponse": { "required": [ "authentication_url" ], "type": "object", "properties": { "authentication_url": { "type": "string", "description": "The OAuth 2.0 authentication URL to use to authenticate app client requests.", "example": "https://localhost:5001/connect/token" } } }, "AuthSettingsResponse": { "required": [ "providers", "registration_enabled" ], "type": "object", "properties": { "providers": { "type": "array", "items": { "type": "string" }, "description": "The available authentication providers (e.g., \"Email\", \"Google\", \"GitHub\").", "example": [ "Email", "Google" ] }, "registration_enabled": { "type": "boolean", "description": "Whether self-registration is enabled.", "example": true }, "allowed_domain": { "type": [ "null", "string" ], "description": "If set, only email addresses from this domain can register.", "example": "example.com" } } }, "Candidate": { "required": [ "id", "title" ], "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "image": { "type": [ "null", "string" ] }, "matched_queries": { "type": [ "null", "array" ], "items": { "type": "string" } }, "fields": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CandidateFields" } ] } } }, "CandidateFields": { "type": "object", "additionalProperties": {} }, "ColumnInfo": { "required": [ "name", "type" ], "type": "object", "properties": { "name": { "type": "string", "description": "The column name.", "example": "timestamp" }, "type": { "type": "string", "description": "The ClickHouse type of the column (e.g. String, DateTime64(3, 'UTC')).", "example": "DateTime64(3, 'UTC')" }, "default_expression": { "type": [ "null", "string" ], "description": "The default-value expression for the column, if any.", "example": "now()" }, "comment": { "type": [ "null", "string" ], "description": "The column comment, if any.", "example": "The time at which the event occurred." } }, "description": "A column in a User Behavior Insights ClickHouse table." }, "ComparisonSummary": { "required": [ "improved", "regressed", "unchanged" ], "type": "object", "properties": { "improved": { "type": "integer", "description": "The number of queries that improved relative to the baseline.", "format": "int32", "example": 42 }, "regressed": { "type": "integer", "description": "The number of queries that regressed relative to the baseline.", "format": "int32", "example": 15 }, "unchanged": { "type": "integer", "description": "The number of queries that were unchanged relative to the baseline.", "format": "int32", "example": 193 } }, "description": "A summary of how queries changed between the runs." }, "CorpusResponse": { "required": [ "id", "name", "created" ], "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the corpus.", "example": "01JRVX6GG4XMSM55XBC3E518DY" }, "name": { "type": "string", "description": "The name of the corpus.", "example": "Movies" }, "description": { "type": [ "null", "string" ], "description": "A description of the corpus.", "example": "Movies from TMDB" }, "created": { "type": "string", "description": "The datetime at which the corpus was created.", "format": "date-time", "example": "2026-05-13T10:30:00Z" }, "updated": { "type": [ "null", "string" ], "description": "The datetime at which the corpus was last updated.", "format": "date-time", "example": "2026-05-14T11:00:00Z" }, "endpoint_count": { "type": "integer", "description": "The number of endpoints associated with this corpus.", "format": "int32", "example": 3 } } }, "CreateAiJudgeRequest": { "required": [ "name", "ai_provider_id", "model", "prompt_template" ], "type": "object", "properties": { "name": { "type": "string", "description": "The name for the AI judge.", "example": "GPT-4o" }, "description": { "type": [ "null", "string" ], "description": "A description for the AI judge.", "example": "Judges relevance of movie search results on a 0-4 scale." }, "ai_provider_id": { "type": "string", "description": "The configured AI provider this judge invokes.", "example": "01JRVX6GG4XMSM55XBC3E518DY" }, "model": { "type": "string", "description": "The model identifier.", "example": "gpt-4o" }, "prompt_template": { "type": "string", "description": "The Handlebars prompt template the judge sends to the model.", "example": "Rate the relevance of the result {{candidate.title}} for the query \"{{query}}\" on a scale of 0-4." }, "max_concurrency": { "type": [ "null", "integer" ], "description": "Maximum number of concurrent LLM requests during a judging run. Defaults to 5. Range: 1-50.", "format": "int32", "example": 5 }, "batch_size": { "type": [ "null", "integer" ], "description": "Number of candidates per prompt. Null or 1 means one candidate per LLM call.\n Values greater than 1 batch multiple candidates for the same query into a single prompt. Range: 1-20.", "format": "int32", "example": 5 }, "include_images": { "type": [ "null", "boolean" ], "description": "Whether to include candidate images in the prompt. Requires a vision-capable model.", "example": false } } }, "CreateAiProviderRequest": { "required": [ "type" ], "type": "object", "anyOf": [ { "$ref": "#/components/schemas/CreateAiProviderRequestCreateOpenAiProviderRequest" }, { "$ref": "#/components/schemas/CreateAiProviderRequestCreateAnthropicProviderRequest" }, { "$ref": "#/components/schemas/CreateAiProviderRequestCreateAzureOpenAiProviderRequest" }, { "$ref": "#/components/schemas/CreateAiProviderRequestCreateOllamaProviderRequest" }, { "$ref": "#/components/schemas/CreateAiProviderRequestCreateCustomProviderRequest" }, { "$ref": "#/components/schemas/CreateAiProviderRequestCreateAmazonBedrockProviderRequest" } ], "description": "Polymorphic create body for an AI provider. The discriminator type selects the\n concrete shape; required fields vary per provider.", "discriminator": { "propertyName": "type", "mapping": { "openai": "#/components/schemas/CreateAiProviderRequestCreateOpenAiProviderRequest", "anthropic": "#/components/schemas/CreateAiProviderRequestCreateAnthropicProviderRequest", "azure_openai": "#/components/schemas/CreateAiProviderRequestCreateAzureOpenAiProviderRequest", "ollama": "#/components/schemas/CreateAiProviderRequestCreateOllamaProviderRequest", "custom": "#/components/schemas/CreateAiProviderRequestCreateCustomProviderRequest", "amazon_bedrock": "#/components/schemas/CreateAiProviderRequestCreateAmazonBedrockProviderRequest" } } }, "CreateAiProviderRequestCreateAmazonBedrockProviderRequest": { "required": [ "aws_region", "access_key_id", "secret_access_key", "name" ], "properties": { "type": { "enum": [ "amazon_bedrock" ], "type": "string" }, "aws_region": { "type": "string", "description": "The AWS region in which Bedrock is provisioned, e.g. us-east-1.", "example": "us-east-1" }, "access_key_id": { "type": "string", "description": "The AWS access key ID.", "example": "AKIAIOSFODNN7EXAMPLE" }, "secret_access_key": { "type": "string", "description": "The AWS secret access key. Encrypted at rest and never returned in read responses.", "example": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" }, "name": { "type": "string", "description": "A human-readable name for the provider, used to identify it in the UI and when linking judges.", "example": "Production OpenAI" } }, "description": "Create body for an Amazon Bedrock provider. Authenticates with AWS access keys against a region." }, "CreateAiProviderRequestCreateAnthropicProviderRequest": { "required": [ "api_key", "name" ], "properties": { "type": { "enum": [ "anthropic" ], "type": "string" }, "api_key": { "type": "string", "description": "The Anthropic API key. Encrypted at rest and never returned in read responses.", "example": "sk-ant-api03-aBcDeFgHiJkLmNoPqRsTuVwXyZ" }, "name": { "type": "string", "description": "A human-readable name for the provider, used to identify it in the UI and when linking judges.", "example": "Production OpenAI" } }, "description": "Create body for an Anthropic provider. Talks to api.anthropic.com — endpoint URL is implicit." }, "CreateAiProviderRequestCreateAzureOpenAiProviderRequest": { "required": [ "endpoint_url", "api_key", "name" ], "properties": { "type": { "enum": [ "azure_openai" ], "type": "string" }, "endpoint_url": { "type": "string", "description": "The Azure OpenAI resource endpoint, e.g. https://my-resource.openai.azure.com/.", "example": "https://my-resource.openai.azure.com/" }, "api_key": { "type": "string", "description": "The Azure OpenAI API key. Encrypted at rest and never returned in read responses.", "example": "aBcDeFgHiJkLmNoPqRsTuVwXyZ1234567890" }, "name": { "type": "string", "description": "A human-readable name for the provider, used to identify it in the UI and when linking judges.", "example": "Production OpenAI" } }, "description": "Create body for an Azure OpenAI provider. Each Azure tenant has its own endpoint URL." }, "CreateAiProviderRequestCreateCustomProviderRequest": { "required": [ "endpoint_url", "name" ], "properties": { "type": { "enum": [ "custom" ], "type": "string" }, "endpoint_url": { "type": "string", "description": "The endpoint URL of the OpenAI-compatible API.", "example": "https://llm.internal.example.com/v1/" }, "api_key": { "type": [ "null", "string" ], "description": "An optional API key, if the custom endpoint requires one. Encrypted at rest and never returned.", "example": "sk-custom-aBcDeFgHiJkLmNoPqRsTuVwXyZ" }, "name": { "type": "string", "description": "A human-readable name for the provider, used to identify it in the UI and when linking judges.", "example": "Production OpenAI" } }, "description": "Create body for a custom OpenAI-compatible provider. Use this for any deployment that exposes\n the OpenAI Chat Completions API at a configurable URL (e.g. vLLM, LM Studio, LiteLLM)." }, "CreateAiProviderRequestCreateOllamaProviderRequest": { "required": [ "endpoint_url", "name" ], "properties": { "type": { "enum": [ "ollama" ], "type": "string" }, "endpoint_url": { "type": "string", "description": "The Ollama server endpoint, e.g. http://localhost:11434/.", "example": "http://localhost:11434/" }, "name": { "type": "string", "description": "A human-readable name for the provider, used to identify it in the UI and when linking judges.", "example": "Production OpenAI" } }, "description": "Create body for an Ollama provider. Used for self-hosted Ollama deployments — no API key required." }, "CreateAiProviderRequestCreateOpenAiProviderRequest": { "required": [ "api_key", "name" ], "properties": { "type": { "enum": [ "openai" ], "type": "string" }, "api_key": { "type": "string", "description": "The OpenAI API key. Encrypted at rest and never returned in read responses.", "example": "sk-proj-aBcDeFgHiJkLmNoPqRsTuVwXyZ" }, "name": { "type": "string", "description": "A human-readable name for the provider, used to identify it in the UI and when linking judges.", "example": "Production OpenAI" } }, "description": "Create body for an OpenAI provider. Talks to api.openai.com — endpoint URL is implicit." }, "CreateAnalysisRequest": { "required": [ "endpoint_id", "query_set_id", "query_template_ids", "baseline", "name" ], "type": "object", "properties": { "endpoint_id": { "type": "string", "description": "The unique identifier of the search endpoint to target for evaluation.", "example": "01JRVX6GG4XMSM55XBC3E518DY" }, "query_set_id": { "type": "string", "description": "The unique identifier of the query set to use.", "example": "01JRVX6GG4XMSM55XBC3E518E2" }, "query_template_ids": { "type": "array", "items": { "type": "string" }, "description": "The unique identifiers of the query templates to use", "example": [ "01JRVX6GG4XMSM55XBC3E518E3", "01JRVX6GG4XMSM55XBC3E518E4" ] }, "baseline": { "type": "string", "description": "The unique identifier of the query template to use as the baseline", "example": "01JRVX6GG4XMSM55XBC3E518E3" }, "name": { "type": "string", "description": "A name for the evaluation", "example": "Movies analysis" } } }, "CreateAnalysisResponse": { "required": [ "id" ], "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the created analysis", "example": "01JRVX6GG4XMSM55XBC3E518E5" } } }, "CreateAppClientRequest": { "required": [ "name", "description" ], "type": "object", "properties": { "name": { "type": "string", "description": "A name for the app client. The name **must** be unique", "example": "Search Indexer" }, "description": { "type": "string", "description": "A description for the app client.", "example": "App client used by the indexing pipeline" }, "roles": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "The roles to assign to the app client. Members can only assign roles they have.\n If not specified, the app client inherits all of the member's roles.", "example": [ "Admin" ] } } }, "CreateAppClientResponse": { "required": [ "client_secret", "id", "name", "description", "roles", "client_id", "client_secret_hint", "created" ], "type": "object", "properties": { "client_secret": { "type": "string", "description": "The client secret of the app client used for OAuth 2.0 authentication.\n The client secret is presented only **once**, so make a note of it.", "example": "s3cr3t_v4lu3_8sK9pQ2mZ7xN1rT4uW6yA1b2" }, "id": { "type": "string", "description": "The unique identifier for the app client", "example": "01JRVX6GG4XMSM55XBC3E518DY" }, "name": { "type": "string", "description": "The name of the app client", "example": "Search Indexer" }, "description": { "type": "string", "description": "A description for the app client", "example": "App client used by the indexing pipeline" }, "roles": { "type": "array", "items": { "type": "string" }, "description": "The roles assigned to the app client", "example": [ "Admin" ] }, "client_id": { "type": "string", "description": "The client ID of the app client used for OAuth 2.0 authentication", "example": "01JRVX6GG4XMSM55XBC3E518E0" }, "client_secret_hint": { "type": "string", "description": "A hint for the client secret used for OAuth 2.0 authentication, to help\n identify credentials.", "example": "...A1b2" }, "last_used": { "type": [ "null", "string" ], "description": "The datetime that the app client was last used to authenticate.", "format": "date-time", "example": "2026-05-13T10:30:00Z" }, "created": { "type": "string", "description": "The datetime that the app client was created.", "format": "date-time", "example": "2026-05-01T09:00:00Z" }, "updated": { "type": [ "null", "string" ], "description": "The datetime that the app client was updated.", "format": "date-time", "example": "2026-05-10T12:00:00Z" } } }, "CreateCorpusRequest": { "required": [ "name" ], "type": "object", "properties": { "name": { "type": "string", "description": "The name of the corpus.", "example": "Movies" }, "description": { "type": [ "null", "string" ], "description": "An optional description of the corpus.", "example": "Movies from TMDB" } } }, "CreateEndpointRequest": { "required": [ "name", "url", "type", "method", "candidates_mapping" ], "type": "object", "properties": { "name": { "type": "string", "description": "A name for the endpoint.", "example": "Movies" }, "description": { "type": [ "null", "string" ], "description": "A description for the endpoint.", "example": "Movies from TMDB" }, "url": { "type": "string", "description": "The url of the endpoint.", "example": "https://localhost:9200/movies/_search" }, "type": { "$ref": "#/components/schemas/EndpointType" }, "method": { "type": "string", "description": "The HTTP method.\n The page endpoint type only supports the GET method.", "example": "GET" }, "authentication": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AuthenticationCredentials" } ] }, "corpus_id": { "type": [ "null", "string" ], "description": "The unique identifier of the corpus this endpoint provides access to.\n If not specified, a new corpus will be created with the endpoint's name.", "example": "01JRVX6GG4XMSM55XBC3E518DZ" }, "candidates_mapping": { "type": "string", "description": "A [JMESPath](https://jmespath.org/) expression or JavaScript script to execute on the endpoint response\n that transforms it into a search result structure that Releval can consume.\n The page endpoint type supports a JavaScript script that executes in a browser context with the endpoint\n response and has access to the DOM and any other scripts loaded by the response. The script **must** transform\n the response into a JSON string search result structure.\n All other endpoint types support a JMESPath expression to transform the endpoint response into\n JSON search result structure.", "example": "{ total: (hits.total.value || hits.total), candidates: hits.hits[].{ id: _id, title: _source.title, image: _source.image, fields: _source } }" } }, "example": { "name": "Movies", "description": "Movies from TMDB", "url": "https://localhost:9200/movies/_search", "type": "elasticsearch", "method": "GET", "authentication": { "type": "basic", "username": "elastic", "password": "password" }, "candidates_mapping": "{ total: (hits.total.value || hits.total), candidates: hits.hits[].{ id: _id, title: _source.title, image: _source.image, fields: _source } }" } }, "CreateEvaluationRequest": { "required": [ "name", "endpoint_id", "query_template_id", "query_set_id" ], "type": "object", "properties": { "name": { "type": "string", "description": "The name for the evaluation.", "example": "Popular Movies" }, "description": { "type": [ "null", "string" ], "description": "A description for the evaluation.", "example": "Popular movies in the last week" }, "endpoint_id": { "type": "string", "description": "The unique identifier of the endpoint to use for evaluation.", "example": "01JRW2RSHZ53JD8ZJY8Y6AV9A0" }, "query_template_id": { "type": "string", "description": "The unique identifier of the query template to use for evaluation.", "example": "01JRW2S4V308HTQH4850KDBK6M" }, "query_set_id": { "type": "string", "description": "The unique identifier of the query set to use for evaluation.", "example": "01JRW2SAFFEFXC1M7MZF7KPHWS" } } }, "CreateEvaluationRunRequest": { "required": [ "name", "metrics" ], "type": "object", "properties": { "name": { "type": "string", "description": "A name for the evaluation run.", "example": "Movies baseline run" }, "description": { "type": [ "null", "string" ], "description": "An optional description for the evaluation run.", "example": "Initial evaluation against the Movies endpoint" }, "scale": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EvaluationScale" } ] }, "tags": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Optional tags for the evaluation run.", "example": [ "commit:abc123", "staging", "experiment-v2" ] }, "metrics": { "type": "array", "items": { "type": "string" }, "description": "The metrics to use. Available metrics are:\n MAPDCG@kNDCG@kERR@kMRR@kBest@k", "example": [ "NDCG@10", "MAP", "MRR@10" ] }, "body": { "type": [ "null", "string" ], "description": "Optional body template override. If not specified, uses the evaluation's query template body.", "example": { "query": { "match": { "title": "{{query}}" } } } }, "query_string": { "type": [ "null", "string" ], "description": "Optional query string template override. If not specified, uses the evaluation's query template query string.", "example": "?size={{size}}" }, "content_type": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/QueryTemplateContentType" } ] }, "headers": { "type": [ "null", "object" ], "additionalProperties": { "type": "string" }, "description": "Optional headers override.", "example": { "X-Custom-Header": "value" } } } }, "CreateQueryIdsRequest": { "required": [ "queries" ], "type": "object", "properties": { "queries": { "type": "array", "items": { "$ref": "#/components/schemas/Query" }, "description": "An array of queries. All queries **must** be text or JSON objects, but not both." } } }, "CreateQueryIdsResponse": { "required": [ "ids" ], "type": "object", "properties": { "ids": { "type": "array", "items": { "$ref": "#/components/schemas/QueryIdResponse" }, "description": "The collection of generated query ids" } } }, "CreateQuerySetRequest": { "required": [ "name", "queries" ], "type": "object", "properties": { "name": { "type": "string", "description": "A name for the query set", "example": "Movies" }, "description": { "type": [ "null", "string" ], "description": "A description for the query set", "example": "Movies from TMDB" }, "queries": { "type": "array", "items": { "$ref": "#/components/schemas/Query" }, "description": "An array of queries. All queries **must** be text or JSON objects, but not both." } }, "example": { "name": "Movies", "description": "Movies from TMDB", "queries": [ "Shrek", "The Godfather", "Forrest Gump" ] } }, "CreateQueryTemplateRequest": { "required": [ "name" ], "type": "object", "properties": { "name": { "type": "string", "description": "A name for the query template.\n It is recommended to use a convention that clearly distinguishes templates from one another.", "example": "Multi-match query" }, "query_string": { "type": [ "null", "string" ], "description": "A [Mustache](https://mustache.github.io/) / [Handlebars](https://handlebarsjs.com/) template for the\n query string parameters of an HTTP request. The template should form valid query string parameters for the\n target search endpoints it will be used with.", "example": "?size={{size}}" }, "content_type": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/QueryTemplateContentType" } ] }, "body": { "type": [ "null", "string" ], "description": "A [Mustache](https://mustache.github.io/) / [Handlebars](https://handlebarsjs.com/) template for the request body of an HTTP request.\n The template should form a valid request body for the target search endpoints it will be used with.", "example": { "query": { "match": { "title": "{{query}}" } } } }, "headers": { "type": [ "null", "object" ], "additionalProperties": { "type": "string" }, "description": "A [Mustache](https://mustache.github.io/) / [Handlebars](https://handlebarsjs.com/) template for the HTTP headers of an HTTP request.", "example": { "X-Search-Tenant": "{{tenant}}" } } }, "example": { "name": "match_title", "query_string": "?size={{size}}", "content_type": "json", "body": "{ \"query\": { \"match\": { \"title\": \"{{query}}\" } } }" } }, "CreateTrainingDataRequest": { "required": [ "judgment_list_id", "endpoint_id", "index", "query_template_ids" ], "type": "object", "properties": { "judgment_list_id": { "type": "string", "description": "The unique identifier of the Judgment List", "example": "01JRVX6GG4XMSM55XBC3E518DY" }, "endpoint_id": { "type": "string", "description": "The unique identifier of the endpoint to use for retrieving feature values", "example": "01JRVX6GG4XMSM55XBC3E518DZ" }, "index": { "type": "string", "description": "The index / collection / alias from which to retrieve feature values", "example": "movies" }, "query_template_ids": { "type": "array", "items": { "type": "string" }, "description": "The unique identifiers for the Query Templates used to retrieve features", "example": [ "01JRVX6GG4XMSM55XBC3E518E0", "01JRVX6GG4XMSM55XBC3E518E1" ] } } }, "CreateTrainingDataResponse": { "required": [ "training_run_id" ], "type": "object", "properties": { "training_run_id": { "type": "string", "description": "The unique identifier of the training run.", "example": "01JRVX6GG4XMSM55XBC3E518DY" } } }, "EndpointResponse": { "required": [ "id", "name", "type", "url", "method", "authentication_type", "corpus_id", "candidates_mapping" ], "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the endpoint.", "example": "01JRVX6GG4XMSM55XBC3E518DY" }, "name": { "type": "string", "description": "The name for the endpoint.", "example": "Movies" }, "description": { "type": [ "null", "string" ], "description": "The description for the endpoint.", "example": "Movies from TMDB" }, "type": { "description": "The type of endpoint.", "$ref": "#/components/schemas/EndpointType" }, "url": { "type": "string", "description": "The url of the endpoint.", "example": "https://localhost:9200/movies/_search" }, "method": { "type": "string", "description": "The HTTP method.", "example": "GET" }, "authentication_type": { "description": "The authentication type for the endpoint.", "$ref": "#/components/schemas/AuthenticationType" }, "corpus_id": { "type": "string", "description": "The unique identifier of the corpus this endpoint provides access to.", "example": "01JRVX6GG4XMSM55XBC3E518DZ" }, "candidates_mapping": { "type": "string", "description": "A [JMESPath](https://jmespath.org/) expression or JavaScript script to execute on the endpoint response\n that transforms it into a search result structure that Releval can consume.", "example": "{ total: (hits.total.value || hits.total), candidates: hits.hits[].{ id: _id, title: _source.title, image: _source.image, fields: _source } }" } }, "example": { "id": "01JRVX6GG4XMSM55XBC3E518DY", "name": "Movies", "description": "Movies from TMDB", "type": "elasticsearch", "url": "https://localhost:9200/movies/_search", "method": "GET", "authentication_type": "basic", "corpus_id": "01JRVX6GG4XMSM55XBC3E518DZ", "candidates_mapping": "{ total: (hits.total.value || hits.total), candidates: hits.hits[].{ id: _id, title: _source.title, image: _source.image, fields: _source } }" } }, "EndpointType": { "enum": [ "api", "page", "elasticsearch", "opensearch", "vespa", "solr" ], "description": "The type of endpoint.", "example": "elasticsearch" }, "EvaluationQueryExecution": { "type": "object", "properties": { "body": { "type": [ "null", "string" ], "description": "The request body executed", "example": { "query": { "match": { "title": "Shrek" } } } }, "url": { "type": [ "null", "string" ], "description": "The URL executed, including query string parameters.", "example": "https://localhost:9200/movies/_search?size=10" }, "method": { "type": [ "null", "string" ], "description": "The HTTP method used for execution", "example": "POST" }, "content_type": { "type": [ "null", "string" ], "description": "The content type of the request", "example": "application/json" } }, "description": "Details about the execution" }, "EvaluationQueryForEvaluationResponse": { "required": [ "id", "query" ], "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the query.", "example": "01JRVX6GG4XMSM55XBC3E518DB" }, "query": { "$ref": "#/components/schemas/Query" } }, "description": "The query context for the result." }, "EvaluationQueryResponse": { "required": [ "id", "query", "execution", "created" ], "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the query.", "example": "01JRVX6GG4XMSM55XBC3E518DY" }, "query": { "$ref": "#/components/schemas/Query" }, "execution": { "$ref": "#/components/schemas/EvaluationQueryExecution" }, "total_candidates": { "type": "integer", "description": "The total number of candidates for the query, as reported by the search endpoint.", "format": "int64", "example": 1500 }, "status_code": { "type": [ "null", "integer" ], "description": "The HTTP response status code from executing the query", "format": "int32", "example": 200 }, "message": { "type": [ "null", "string" ], "description": "A failure message, if the execution failed.", "example": "Connection refused" }, "failed": { "type": [ "null", "boolean" ], "description": "Whether the execution failed", "example": false }, "query_item_id": { "type": [ "null", "string" ], "description": "The unique identifier for the query from the query set.", "example": 12345 }, "oid": { "type": [ "null", "string" ], "description": "The hash of the full query object, used for corpus-scoped judgment lookups.", "example": 67890 }, "created": { "type": "string", "description": "The datetime at which this evaluation query was created.", "format": "date-time", "example": "2026-05-13T10:30:00Z" }, "updated": { "type": [ "null", "string" ], "description": "The datetime at which this evaluation query was updated.", "format": "date-time", "example": "2026-05-13T10:31:00Z" }, "metrics": { "type": "object", "additionalProperties": { "type": "number", "format": "double" }, "description": "The latest calculated metrics for the evaluation run.", "example": { "NDCG@10": 0.847, "MAP": 0.612 } } }, "example": { "id": "01JRVX6GG4XMSM55XBC3E518DY", "query": { "query": "Shrek" }, "execution": { "body": "{ \"query\": { \"match\": { \"title\": \"Shrek\" } } }", "url": "https://localhost:9200/movies/_search?size=10", "method": "POST", "content_type": "application/json" }, "total_candidates": 1500, "status_code": 200, "failed": false, "query_item_id": "12345", "oid": "67890", "created": "2026-05-13T10:30:00+00:00", "updated": "2026-05-13T10:31:00+00:00", "metrics": { "NDCG@10": 0.847, "MAP": 0.612 } } }, "EvaluationQueryResultResponse": { "required": [ "id", "position", "evaluation_query_id", "created", "candidate" ], "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the result.", "example": "01JRVX6GG4XMSM55XBC3E518DA" }, "position": { "type": "integer", "description": "The position/rank of the result in the list of presented results", "format": "int32", "example": 1 }, "evaluation_query_id": { "type": [ "null", "string" ], "description": "The unique identifier of the evaluation query to which this result relates", "example": "01JRVX6GG4XMSM55XBC3E518DB" }, "created": { "type": "string", "description": "The datetime at which this result was created.", "format": "date-time", "example": "2026-05-13T10:30:00Z" }, "updated": { "type": [ "null", "string" ], "description": "The datetime at which this result was updated.", "format": "date-time", "example": "2026-05-13T10:31:00Z" }, "candidate": { "$ref": "#/components/schemas/Candidate" } }, "example": { "id": "01JRVX6GG4XMSM55XBC3E518DA", "position": 1, "evaluation_query_id": "01JRVX6GG4XMSM55XBC3E518DB", "created": "2026-05-13T10:30:00+00:00", "updated": "2026-05-13T10:31:00+00:00", "candidate": { "id": "tt0126029", "title": "Shrek", "image": "https://example.com/shrek.jpg", "fields": { "year": 2001 } } } }, "EvaluationResponse": { "required": [ "id", "name", "created" ], "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the evaluation", "example": "01JRVX6GG4XMSM55XBC3E518E6" }, "name": { "type": "string", "description": "The name of the evaluation", "example": "Popular Movies" }, "description": { "type": [ "null", "string" ], "description": "A description for the evaluation.", "example": "Popular movies in the last week" }, "endpoint_id": { "type": [ "null", "string" ], "description": "The unique identifier of the endpoint used by the evaluation.", "example": "01JRVX6GG4XMSM55XBC3E518DY" }, "query_template_id": { "type": [ "null", "string" ], "description": "The unique identifier of the query template used by the evaluation.", "example": "01JRVX6GG4XMSM55XBC3E518E3" }, "query_set_id": { "type": [ "null", "string" ], "description": "The unique identifier of the query set used by the evaluation.", "example": "01JRVX6GG4XMSM55XBC3E518E2" }, "created": { "type": "string", "description": "The datetime at which the evaluation was created", "format": "date-time", "example": "2026-05-13T10:30:00Z" }, "updated": { "type": [ "null", "string" ], "description": "The datetime at which the evaluation was last updated", "format": "date-time", "example": "2026-05-14T09:15:00Z" } } }, "EvaluationRunResponse": { "required": [ "id", "evaluation_id", "name", "scale", "metrics", "status", "created", "query_count", "candidates_mapping" ], "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the evaluation run.", "example": "01JRVX6GG4XMSM55XBC3E518E7" }, "evaluation_id": { "type": "string", "description": "The unique identifier of the evaluation to which this run belongs.", "example": "01JRVX6GG4XMSM55XBC3E518E6" }, "name": { "type": "string", "description": "The name of the evaluation run.", "example": "Run 1" }, "description": { "type": [ "null", "string" ], "description": "A description of the evaluation run.", "example": "Initial baseline run" }, "scale": { "description": "The relevance scale used for the evaluation.", "$ref": "#/components/schemas/EvaluationScale" }, "metrics": { "type": "object", "additionalProperties": { "type": [ "null", "number" ], "format": "double" }, "description": "The list of evaluation metrics used in the run.", "example": { "NDCG@10": 0.82, "P@10": 0.75 } }, "status": { "description": "The status of the evaluation run.", "$ref": "#/components/schemas/EvaluationRunStatus" }, "created": { "type": "string", "description": "The datetime at which the evaluation run was created.", "format": "date-time", "example": "2026-05-13T10:30:00Z" }, "member_id": { "type": [ "null", "string" ], "description": "The unique identifier of the member who created the evaluation run.", "example": "01JRVX6GG4XMSM55XBC3E518E8" }, "query_count": { "type": "integer", "description": "The count of queries in this evaluation run", "format": "int32", "example": 50 }, "candidates_mapping": { "type": "string", "description": "A [JMESPath](https://jmespath.org/) expression or JavaScript script to execute on the endpoint response\n that transforms it into a search result structure that Releval can consume.", "example": "{ total: (hits.total.value || hits.total), candidates: hits.hits[].{ id: _id, title: _source.title, image: _source.image, fields: _source } }" }, "content_type": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/QueryTemplateContentType" } ] }, "body": { "type": [ "null", "string" ], "description": "A [Mustache](https://mustache.github.io/) / [Handlebars](https://handlebarsjs.com/) template for the request body of an HTTP request.", "example": { "query": { "match": { "title": "{{query}}" } } } }, "query_string": { "type": [ "null", "string" ], "description": "A [Mustache](https://mustache.github.io/) / [Handlebars](https://handlebarsjs.com/) template for the query string parameters of an HTTP request.", "example": "?size={{size}}" }, "headers": { "type": [ "null", "object" ], "additionalProperties": { "type": "string" }, "description": "A [Mustache](https://mustache.github.io/) / [Handlebars](https://handlebarsjs.com/) template for the HTTP headers of an HTTP request.", "example": { "Content-Type": "application/json" } }, "tags": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Tags associated with the evaluation run.", "example": [ "baseline", "movies" ] }, "corpus_id": { "type": [ "null", "string" ], "description": "The unique identifier of the corpus associated with this run's evaluation endpoint.", "example": "01JRVX6GG4XMSM55XBC3E518DZ" } }, "description": "Represents a response object for an evaluation run." }, "EvaluationRunStatus": { "enum": [ "pending", "queued", "running", "completed", "failed", "locked", "cancelled" ], "description": "The status of the evaluation run.", "example": "completed" }, "EvaluationRunStatusResponse": { "required": [ "id", "status", "updated" ], "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the evaluation run.", "example": "01JRVX6GG4XMSM55XBC3E518DY" }, "status": { "description": "The status of the evaluation run.", "$ref": "#/components/schemas/EvaluationRunStatus" }, "updated": { "type": "string", "description": "The datetime that the evaluation run was updated.", "format": "date-time", "example": "2026-05-13T10:30:00Z" } } }, "EvaluationScale": { "enum": [ "binary", "graded", "detailed" ], "description": "The relevance scale used for the evaluation.", "example": "graded" }, "EventAttributes": { "type": "object", "properties": { "object": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ObjectDetails" } ] }, "position": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Position" } ] } }, "description": "Extensible details about a specific event. For example, the specific identifier of the user (user_id)." }, "ExecutionQuery": { "required": [ "method", "endpoint", "content_type", "body" ], "type": "object", "properties": { "method": { "$ref": "#/components/schemas/HttpMethod" }, "endpoint": { "type": "string" }, "content_type": { "type": "string" }, "body": { "type": "string" } }, "description": "The query that was executed." }, "ExecutionResponse": { "required": [ "id", "name", "execution_index", "baseline", "query", "duration_ms" ], "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the execution.", "example": "01JRVX6GG4XMSM55XBC3E518DY" }, "name": { "type": "string", "description": "The name for the execution", "example": "Shrek" }, "execution_index": { "type": "integer", "description": "The index for the execution in all executions in this analysis.\n Used to group executions for different queries.", "format": "int32", "example": 0 }, "baseline": { "type": "boolean", "description": "Whether the execution is the baseline.", "example": true }, "query": { "$ref": "#/components/schemas/ExecutionQuery" }, "result": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ExecutionResult" } ] }, "duration_ms": { "type": "number", "description": "The duration in milliseconds of the execution.", "format": "double", "example": 123.45 } }, "example": { "id": "01JRVX6GG4XMSM55XBC3E518DY", "name": "Shrek", "execution_index": 0, "baseline": true, "query": { "method": "POST", "endpoint": "/movies/_search", "content_type": "application/json", "body": "{ \"query\": { \"match\": { \"title\": \"Shrek\" } } }" }, "result": { "candidates": [ { "id": "808", "title": "Shrek", "image": "https://image.tmdb.org/t/p/w500/shrek.jpg" } ], "total": 1 }, "duration_ms": 45.6 } }, "ExecutionResult": { "required": [ "candidates", "total", "failure" ], "type": "object", "properties": { "candidates": { "type": "array", "items": { "$ref": "#/components/schemas/Candidate" } }, "total": { "type": "integer", "format": "int64" }, "failure": { "type": [ "null", "string" ] } }, "description": "The result of executing the query." }, "ForgotPasswordRequest": { "required": [ "email" ], "type": "object", "properties": { "email": { "type": "string", "description": "The email address to send the reset password code to, if a member with that confirmed email address already exists.", "example": "member@example.com" } } }, "GetAnalysisResponse": { "required": [ "id", "name", "created", "queries" ], "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the analysis", "example": "01JRVX6GG4XMSM55XBC3E518DY" }, "name": { "type": "string", "description": "The name of the analysis", "example": "Search relevance baseline" }, "created": { "type": "string", "description": "The datetime at which the analysis was created", "format": "date-time", "example": "2026-05-13T10:30:00Z" }, "executions_processed": { "type": "integer", "description": "The number of executions processed.", "format": "int64", "example": 42 }, "queries": { "type": "array", "items": { "$ref": "#/components/schemas/QueryAnalysis" }, "description": "The queries" } }, "example": { "id": "01JRVX6GG4XMSM55XBC3E518DY", "name": "Search relevance baseline", "created": "2026-05-13T10:30:00+00:00", "executions_processed": 42, "queries": [ { "name": "Shrek", "baseline": true, "mean_duration_ms": 45.6 }, { "name": "The Godfather", "baseline": false, "mean_duration_ms": 38.2 }, { "name": "The Matrix", "baseline": false, "mean_duration_ms": 52.1 } ] } }, "HttpMethod": { "enum": [ "GET", "POST", "PUT", "DELETE" ], "type": "string" }, "IFormFile": { "type": "string", "format": "binary" }, "Info": { "required": [ "username", "id", "login_providers", "roles" ], "type": "object", "properties": { "email": { "type": [ "null", "string" ], "description": "The email address associated with the authenticated member.", "example": "member@example.com" }, "is_email_confirmed": { "type": [ "null", "boolean" ], "description": "Indicates whether the email address has been confirmed yet.\n Only valid when the authenticated member has signed up by email.", "example": false }, "picture": { "type": [ "null", "string" ], "description": "The URL of the authenticated member's profile picture, if available", "example": "https://www.gravatar.com/avatar/5658ffccee7f0ebfda2b226238b1eb6e" }, "name": { "type": [ "null", "string" ], "description": "The member's name", "example": "Example Member" }, "username": { "type": "string", "description": "The username", "example": "member@example.com" }, "id": { "type": "string", "description": "The member id", "example": "01JPS181CTZ3YZGVFTJCXFKW53" }, "login_providers": { "type": "array", "items": { "type": "string" }, "description": "The list of login providers associated with the authenticated member.", "example": [ "Email" ] }, "roles": { "type": "array", "items": { "type": "string" }, "description": "The list of roles associated with the authenticated member.", "example": [ "Admin" ] } } }, "InfoRequest": { "type": "object", "properties": { "name": { "type": [ "null", "string" ], "description": "The member's name", "example": "Example Member" }, "email": { "type": [ "null", "string" ], "description": "The email address for the member.", "example": "member@example.com" } } }, "InviteMemberRequest": { "required": [ "email", "role" ], "type": "object", "properties": { "email": { "type": "string", "description": "The email address of the member to invite.", "example": "member@example.com" }, "role": { "type": "string", "description": "The role to assign to the member.", "example": "Member" } } }, "Judgment": { "required": [ "candidate_id", "grade" ], "type": "object", "properties": { "candidate_id": { "type": "string", "description": "The identifier of the candidate the judgment applies to.", "example": "tt0111161" }, "grade": { "type": "integer", "description": "The grade assigned to the candidate on the judgment list's scale.", "format": "int32", "example": 3 }, "member_id": { "type": [ "null", "string" ], "description": "The member ID who made the judgment (admin only)", "example": "01JRVX6GG4XMSM55XBC3E518E0" }, "user_name": { "type": [ "null", "string" ], "description": "The member's display name (admin only)", "example": "alice" }, "ai_judge_id": { "type": [ "null", "string" ], "description": "The AI judge ID that made the judgment, if applicable", "example": "01JRVX6GG4XMSM55XBC3E518E1" }, "ai_judge_name": { "type": [ "null", "string" ], "description": "The AI judge name, if applicable", "example": "Claude Judge" }, "reasoning": { "type": [ "null", "string" ], "description": "Chain-of-thought reasoning for AI judgments", "example": "The candidate's title and overview closely match the query intent." } } }, "JudgmentListResponse": { "required": [ "id", "name", "created", "type", "judgment_stats" ], "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the judgment list.", "example": "01JRVX6GG4XMSM55XBC3E518DY" }, "name": { "type": "string", "description": "The name of the judgment list", "example": "Movies judgments" }, "created": { "type": "string", "description": "The datetime that the judgment list was created, formatted to [ISO 8601 standard](https://en.wikipedia.org/wiki/ISO_8601).", "format": "date-time", "example": "2026-05-13T10:30:00Z" }, "type": { "type": "string", "description": "The type of judgments", "example": "explicit" }, "member_id": { "type": [ "null", "string" ], "description": "The unique identifier of the member that created the judgment list.", "example": "01JRVX6GG4XMSM55XBC3E518E0" }, "scale": { "description": "The relevance scale used for the evaluation.", "$ref": "#/components/schemas/EvaluationScale" }, "corpus_id": { "type": [ "null", "string" ], "description": "The unique identifier of the corpus with which this judgment list is associated.", "example": "01JRVX6GG4XMSM55XBC3E518DZ" }, "judgment_stats": { "description": "Statistics about the judgments.", "$ref": "#/components/schemas/JudgmentStats" } }, "example": { "id": "01JRVX6GG4XMSM55XBC3E518DY", "name": "Movies judgments", "created": "2026-05-13T10:30:00+00:00", "type": "explicit", "member_id": "01JRVX6GG4XMSM55XBC3E518E0", "scale": "graded", "corpus_id": "01JRVX6GG4XMSM55XBC3E518DZ", "judgment_stats": { "count": 1500, "min_grade": 0, "max_grade": 4 } } }, "JudgmentResponse": { "required": [ "grade", "created", "candidate_id" ], "type": "object", "properties": { "query_id": { "type": [ "null", "string" ], "description": "The identifier of the evaluation query this judgment was associated with, if any.", "example": "01JRVX6GG4XMSM55XBC3E518E2" }, "grade": { "type": "integer", "description": "The grade assigned to the candidate.", "format": "int32", "example": 3 }, "created": { "type": "string", "description": "When the judgment was created.", "format": "date-time", "example": "2026-05-13T10:30:00Z" }, "member_id": { "type": [ "null", "string" ], "description": "The identifier of the member who made the judgment.", "example": "01JRVX6GG4XMSM55XBC3E518E0" }, "updated": { "type": [ "null", "string" ], "description": "When the judgment was last updated.", "format": "date-time", "example": "2026-05-13T11:15:00Z" }, "candidate_id": { "type": "string", "description": "The identifier of the candidate the judgment applies to.", "example": "tt0111161" }, "ai_judge_id": { "type": [ "null", "string" ], "description": "The identifier of the AI judge that produced the judgment, if applicable.", "example": "01JRVX6GG4XMSM55XBC3E518E1" }, "reasoning": { "type": [ "null", "string" ], "description": "Chain-of-thought reasoning for AI judgments.", "example": "The candidate's title and overview closely match the query intent." } } }, "JudgmentStats": { "required": [ "count" ], "type": "object", "properties": { "count": { "type": "integer", "description": "The count of judgments", "format": "int32", "example": 1500 }, "min_grade": { "type": [ "null", "integer" ], "description": "The minimum grade for judgments.", "format": "uint32", "example": 0 }, "max_grade": { "type": [ "null", "integer" ], "description": "The maximum grade for judgments.", "format": "uint32", "example": 4 } }, "description": "Statistics about the judgments." }, "Licensee": { "type": "object", "properties": { "name": { "type": [ "null", "string" ], "description": "The name of the organization or individual the license is issued to.", "example": "Acme Corporation" }, "email": { "type": [ "null", "string" ], "description": "The email address associated with the license.", "example": "licensing@acme.com" } }, "description": "Information about the license holder." }, "LicenseInfoResponse": { "required": [ "tier", "type" ], "type": "object", "properties": { "is_valid": { "type": "boolean", "description": "Whether the license is valid.", "example": true }, "is_expired": { "type": "boolean", "description": "Whether the license has expired.", "example": false }, "is_fallback": { "type": "boolean", "description": "Whether the service fell back to an individual license due to an invalid external license.", "example": false }, "fallback_reason": { "type": [ "null", "string" ], "description": "The reason for falling back to an individual license, if applicable.", "example": "License signature validation failed" }, "tier": { "description": "The name of the current tier.", "$ref": "#/components/schemas/LicenseTier" }, "type": { "description": "How the current license was issued.", "$ref": "#/components/schemas/LicenseType" }, "licensee": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Licensee" } ] }, "expires_at": { "type": [ "null", "string" ], "description": "When the license expires.", "format": "date-time", "example": "2026-12-31T23:59:59Z" }, "limits": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LicenseLimits" } ] }, "rejected_license": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/RejectedLicenseResponse" } ] } }, "description": "Response containing license information.", "example": { "is_valid": true, "is_expired": false, "is_fallback": false, "tier": "team", "type": "standard", "licensee": { "name": "Acme Corporation", "email": "licensing@acme.com" }, "expires_at": "2026-12-31T23:59:59+00:00", "limits": { "max_members": 10, "max_app_clients": 10 } } }, "LicenseLimits": { "type": "object", "properties": { "max_members": { "type": [ "null", "integer" ], "description": "Maximum number of members allowed. Null means unlimited.", "format": "int32", "example": 25 }, "max_endpoints": { "type": [ "null", "integer" ], "description": "Maximum number of endpoints allowed. Null means unlimited.", "format": "int32", "example": 25 }, "max_query_sets": { "type": [ "null", "integer" ], "description": "Maximum number of query sets allowed. Null means unlimited.", "format": "int32" }, "max_query_templates": { "type": [ "null", "integer" ], "description": "Maximum number of query templates allowed. Null means unlimited.", "format": "int32" }, "max_evaluations": { "type": [ "null", "integer" ], "description": "Maximum number of evaluations allowed. Null means unlimited.", "format": "int32" }, "max_judgment_lists": { "type": [ "null", "integer" ], "description": "Maximum number of judgment lists allowed. Null means unlimited.", "format": "int32" }, "max_app_clients": { "type": [ "null", "integer" ], "description": "Maximum number of app clients allowed. Null means unlimited.", "format": "int32", "example": 10 } }, "description": "The license limits." }, "LicenseTier": { "enum": [ "individual", "team", "enterprise" ], "description": "The name of the current tier.", "example": "team" }, "LicenseType": { "enum": [ "standard", "trial" ], "description": "How the current license was issued.", "example": "standard" }, "ListAiJudgesResponse": { "required": [ "ai_judges", "page", "page_size", "total_count", "total_pages" ], "type": "object", "properties": { "ai_judges": { "type": "array", "items": { "$ref": "#/components/schemas/AiJudgeResponse" }, "description": "The AI judges on the current page." }, "page": { "type": "integer", "description": "The page number (1-based)", "format": "int32", "example": 1 }, "page_size": { "type": "integer", "description": "The page size", "format": "int32", "example": 20 }, "total_count": { "type": "integer", "description": "The total count of items", "format": "int32", "example": 42 }, "total_pages": { "type": "integer", "description": "The total number of pages given the total count and page size", "format": "int32", "example": 3 } }, "example": { "ai_judges": [ { "id": "01JRVX6GG4XMSM55XBC3E518DY", "name": "Relevance Judge", "description": "Judges relevance of movie search results on a 0-4 scale.", "ai_provider_id": "01JRVX6GG4XMSM55XBC3E518E0", "ai_provider_type": "openai", "ai_provider_name": "OpenAI Production", "model": "gpt-4o", "prompt_template": "Rate the relevance of the result {{candidate.title}} for the query \"{{query}}\" on a scale of 0-4.", "max_concurrency": 5, "batch_size": 5, "include_images": false, "member_id": "01JRVX6GG4XMSM55XBC3E518E1", "created": "2026-05-10T09:00:00+00:00", "updated": "2026-05-13T10:30:00+00:00" } ], "page": 1, "page_size": 20, "total_count": 1, "total_pages": 1 } }, "ListAiJudgingRunsResponse": { "required": [ "ai_judging_runs" ], "type": "object", "properties": { "ai_judging_runs": { "type": "array", "items": { "$ref": "#/components/schemas/AiJudgingRunResponse" }, "description": "The AI judging runs." } }, "example": { "ai_judging_runs": [ { "id": "01JRVX6GG4XMSM55XBC3E518DY", "evaluation_run_id": "01JRVX6GG4XMSM55XBC3E518E2", "ai_judge_id": "01JRVX6GG4XMSM55XBC3E518E3", "ai_judge_name": "Relevance Judge", "ai_judge_provider_type": "openai", "status": "running", "progress": 0.75, "total_count": 200, "completed_count": 150, "failed_count": 2, "input_token_count": 125000, "output_token_count": 45000, "initiated_by_member_id": "01JRVX6GG4XMSM55XBC3E518E4", "created": "2026-05-13T10:30:00+00:00", "updated": "2026-05-13T10:45:00+00:00" } ] } }, "ListAiProvidersResponse": { "required": [ "ai_providers", "page", "page_size", "total_count", "total_pages" ], "type": "object", "properties": { "ai_providers": { "type": "array", "items": { "$ref": "#/components/schemas/AiProviderResponse" }, "description": "The AI providers on the current page." }, "page": { "type": "integer", "description": "The page number (1-based)", "format": "int32", "example": 1 }, "page_size": { "type": "integer", "description": "The page size", "format": "int32", "example": 20 }, "total_count": { "type": "integer", "description": "The total count of items", "format": "int32", "example": 42 }, "total_pages": { "type": "integer", "description": "The total number of pages given the total count and page size", "format": "int32", "example": 3 } }, "example": { "ai_providers": [ { "type": "openai", "id": "01JRVX6GG4XMSM55XBC3E518DY", "name": "OpenAI Production", "member_id": "01JRVX6GG4XMSM55XBC3E518E0", "created": "2026-05-10T09:00:00+00:00", "updated": "2026-05-13T10:30:00+00:00" } ], "page": 1, "page_size": 20, "total_count": 1, "total_pages": 1 } }, "ListAnalysesResponse": { "required": [ "analyses" ], "type": "object", "properties": { "analyses": { "type": "array", "items": { "$ref": "#/components/schemas/AnalysisResponse" }, "description": "The list of analyses" } }, "example": { "analyses": [ { "id": "01JRVX6GG4XMSM55XBC3E518DY", "name": "Search relevance baseline", "created": "2026-05-13T10:30:00+00:00", "executions_processed": 100, "executions_count": 100, "status": "completed" }, { "id": "01JRVX6GG4XMSM55XBC3E518DZ", "name": "Title boost experiment", "created": "2026-05-13T11:00:00+00:00", "executions_processed": 42, "executions_count": 100, "status": "running" } ] } }, "ListAppClientsResponse": { "type": "object", "properties": { "app_clients": { "type": "array", "items": { "$ref": "#/components/schemas/AppClientResponse" }, "description": "A collection of app clients." } }, "example": { "app_clients": [ { "id": "01JRVX6GG4XMSM55XBC3E518DY", "name": "Search Indexer", "description": "App client used by the indexing pipeline", "roles": [ "Admin" ], "client_id": "01JRVX6GG4XMSM55XBC3E518E0", "client_secret_hint": "...A1b2", "last_used": "2026-05-13T10:30:00+00:00", "created": "2026-05-01T09:00:00+00:00", "updated": "2026-05-10T12:00:00+00:00" } ] } }, "ListCorporaResponse": { "required": [ "corpora" ], "type": "object", "properties": { "corpora": { "type": "array", "items": { "$ref": "#/components/schemas/CorpusResponse" }, "description": "The list of corpora." } }, "example": { "corpora": [ { "id": "01JRVX6GG4XMSM55XBC3E518DY", "name": "Movies", "description": "Movies from TMDB", "created": "2026-05-13T10:30:00+00:00", "updated": "2026-05-14T11:00:00+00:00", "endpoint_count": 3 }, { "id": "01JRVX6GG4XMSM55XBC3E518DZ", "name": "Products", "description": "E-commerce product catalogue", "created": "2026-05-13T11:00:00+00:00", "endpoint_count": 1 } ] } }, "ListEndpointsResponse": { "required": [ "endpoints", "page", "page_size", "total_count", "total_pages" ], "type": "object", "properties": { "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/EndpointResponse" }, "description": "The list of endpoints" }, "page": { "type": "integer", "description": "The page number (1-based)", "format": "int32", "example": 1 }, "page_size": { "type": "integer", "description": "The page size", "format": "int32", "example": 20 }, "total_count": { "type": "integer", "description": "The total count of items", "format": "int32", "example": 42 }, "total_pages": { "type": "integer", "description": "The total number of pages given the total count and page size", "format": "int32", "example": 3 } }, "example": { "endpoints": [ { "id": "01JRVX6GG4XMSM55XBC3E518DY", "name": "Movies", "description": "Movies from TMDB", "type": "elasticsearch", "url": "https://localhost:9200/movies/_search", "method": "GET", "authentication_type": "basic", "corpus_id": "01JRVX6GG4XMSM55XBC3E518DZ", "candidates_mapping": "{ total: (hits.total.value || hits.total), candidates: hits.hits[].{ id: _id, title: _source.title, image: _source.image, fields: _source } }" } ], "page": 1, "page_size": 20, "total_count": 1, "total_pages": 1 } }, "ListEvaluationQueriesResponse": { "required": [ "queries", "page", "page_size", "total_count", "total_pages" ], "type": "object", "properties": { "queries": { "type": "array", "items": { "$ref": "#/components/schemas/EvaluationQueryResponse" }, "description": "A collection of queries for an evaluation run." }, "page": { "type": "integer", "description": "The page number (1-based)", "format": "int32", "example": 1 }, "page_size": { "type": "integer", "description": "The page size", "format": "int32", "example": 20 }, "total_count": { "type": "integer", "description": "The total count of items", "format": "int32", "example": 42 }, "total_pages": { "type": "integer", "description": "The total number of pages given the total count and page size", "format": "int32", "example": 3 } }, "example": { "queries": [ { "id": "01JRVX6GG4XMSM55XBC3E518DY", "query": { "query": "Shrek" }, "execution": { "body": "{ \"query\": { \"match\": { \"title\": \"Shrek\" } } }", "url": "https://localhost:9200/movies/_search?size=10", "method": "POST", "content_type": "application/json" }, "total_candidates": 1500, "status_code": 200, "failed": false, "query_item_id": "12345", "oid": "67890", "created": "2026-05-13T10:30:00+00:00", "metrics": { "NDCG@10": 0.847 } }, { "id": "01JRVX6GG4XMSM55XBC3E518DZ", "query": { "query": "The Matrix" }, "execution": { "body": "{ \"query\": { \"match\": { \"title\": \"The Matrix\" } } }", "url": "https://localhost:9200/movies/_search?size=10", "method": "POST", "content_type": "application/json" }, "total_candidates": 1200, "status_code": 200, "failed": false, "query_item_id": "12346", "oid": "67891", "created": "2026-05-13T10:30:00+00:00", "metrics": { "NDCG@10": 0.792 } } ], "page": 1, "page_size": 50, "total_count": 2, "total_pages": 1 } }, "ListEvaluationQueryResultsResponse": { "required": [ "evaluation_run_id", "page", "page_size", "total_count", "total_pages" ], "type": "object", "properties": { "evaluation_run_id": { "type": "string", "description": "The unique identifier of the evaluation run to which the results belong", "example": "01JRVX6GG4XMSM55XBC3E518DY" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/EvaluationQueryResultResponse" }, "description": "A collection of results for a query in an evaluation run." }, "page": { "type": "integer", "description": "The page number (1-based)", "format": "int32", "example": 1 }, "page_size": { "type": "integer", "description": "The page size", "format": "int32", "example": 20 }, "total_count": { "type": "integer", "description": "The total count of items", "format": "int32", "example": 42 }, "total_pages": { "type": "integer", "description": "The total number of pages given the total count and page size", "format": "int32", "example": 3 } }, "example": { "evaluation_run_id": "01JRVX6GG4XMSM55XBC3E518DY", "results": [ { "id": "01JRVX6GG4XMSM55XBC3E518R1", "position": 1, "evaluation_query_id": "01JRVX6GG4XMSM55XBC3E518DB", "created": "2026-05-13T10:30:00+00:00", "candidate": { "id": "tt0126029", "title": "Shrek", "fields": { "year": 2001 } } }, { "id": "01JRVX6GG4XMSM55XBC3E518R2", "position": 2, "evaluation_query_id": "01JRVX6GG4XMSM55XBC3E518DB", "created": "2026-05-13T10:30:00+00:00", "candidate": { "id": "tt0298148", "title": "Shrek 2", "fields": { "year": 2004 } } } ], "page": 1, "page_size": 50, "total_count": 2, "total_pages": 1 } }, "ListEvaluationRunsResponse": { "type": "object", "properties": { "runs": { "type": "array", "items": { "$ref": "#/components/schemas/EvaluationRunResponse" }, "description": "A collection of evaluation runs." } }, "example": { "runs": [ { "id": "01JRVX6GG4XMSM55XBC3E518DY", "evaluation_id": "01JRVX6GG4XMSM55XBC3E518E1", "name": "Movies baseline run", "description": "Initial evaluation against the Movies endpoint", "scale": "graded", "metrics": { "NDCG@10": 0.847, "MAP": 0.612 }, "status": "completed", "created": "2026-05-13T10:30:00+00:00", "member_id": "01JRVX6GG4XMSM55XBC3E518M1", "query_count": 100, "candidates_mapping": "{ total: hits.total.value, candidates: hits.hits[].{ id: _id, title: _source.title, fields: _source } }", "content_type": "json", "body": "{ \"query\": { \"match\": { \"title\": \"{{query}}\" } } }", "tags": [ "commit:abc123", "staging" ], "corpus_id": "01JRVX6GG4XMSM55XBC3E518DZ" } ] } }, "ListEvaluationsResponse": { "required": [ "evaluations", "page", "page_size", "total_count", "total_pages" ], "type": "object", "properties": { "evaluations": { "type": "array", "items": { "$ref": "#/components/schemas/EvaluationResponse" }, "description": "The collection of evaluations" }, "page": { "type": "integer", "description": "The page number (1-based)", "format": "int32", "example": 1 }, "page_size": { "type": "integer", "description": "The page size", "format": "int32", "example": 20 }, "total_count": { "type": "integer", "description": "The total count of items", "format": "int32", "example": 42 }, "total_pages": { "type": "integer", "description": "The total number of pages given the total count and page size", "format": "int32", "example": 3 } }, "example": { "evaluations": [ { "id": "01JRVX6GG4XMSM55XBC3E518E6", "name": "Popular Movies", "description": "Popular movies in the last week", "endpoint_id": "01JRVX6GG4XMSM55XBC3E518DY", "query_template_id": "01JRVX6GG4XMSM55XBC3E518E3", "query_set_id": "01JRVX6GG4XMSM55XBC3E518E2", "created": "2026-05-13T10:30:00+00:00", "updated": "2026-05-14T09:15:00+00:00" } ], "page": 1, "page_size": 20, "total_count": 1, "total_pages": 1 } }, "ListExecutionsResponse": { "required": [ "page", "page_size", "total_count", "total_pages" ], "type": "object", "properties": { "executions": { "type": "array", "items": { "$ref": "#/components/schemas/ExecutionResponse" }, "description": "The executions for the given page." }, "page": { "type": "integer", "description": "The page number (1-based)", "format": "int32", "example": 1 }, "page_size": { "type": "integer", "description": "The page size", "format": "int32", "example": 20 }, "total_count": { "type": "integer", "description": "The total count of items", "format": "int32", "example": 42 }, "total_pages": { "type": "integer", "description": "The total number of pages given the total count and page size", "format": "int32", "example": 3 } }, "example": { "executions": [ { "id": "01JRVX6GG4XMSM55XBC3E518DY", "name": "Shrek", "execution_index": 0, "baseline": true, "query": { "method": "POST", "endpoint": "/movies/_search", "content_type": "application/json", "body": "{ \"query\": { \"match\": { \"title\": \"Shrek\" } } }" }, "result": { "candidates": [ { "id": "808", "title": "Shrek", "image": "https://image.tmdb.org/t/p/w500/shrek.jpg" } ], "total": 1 }, "duration_ms": 45.6 } ], "page": 1, "page_size": 25, "total_count": 100, "total_pages": 4 } }, "ListJudgmentListsResponse": { "required": [ "judgment_lists" ], "type": "object", "properties": { "judgment_lists": { "type": "array", "items": { "$ref": "#/components/schemas/JudgmentListResponse" }, "description": "The collection of judgment lists" } }, "example": { "judgment_lists": [ { "id": "01JRVX6GG4XMSM55XBC3E518DY", "name": "Movies judgments", "created": "2026-05-13T10:30:00+00:00", "type": "explicit", "member_id": "01JRVX6GG4XMSM55XBC3E518E0", "scale": "graded", "corpus_id": "01JRVX6GG4XMSM55XBC3E518DZ", "judgment_stats": { "count": 1500, "min_grade": 0, "max_grade": 4 } }, { "id": "01JRVX6GG4XMSM55XBC3E518E3", "name": "Books judgments", "created": "2026-05-10T09:00:00+00:00", "type": "golden", "member_id": "01JRVX6GG4XMSM55XBC3E518E0", "scale": "binary", "corpus_id": "01JRVX6GG4XMSM55XBC3E518E4", "judgment_stats": { "count": 800, "min_grade": 0, "max_grade": 1 } } ] } }, "ListJudgmentsResponse": { "required": [ "judgments" ], "type": "object", "properties": { "judgments": { "type": "array", "items": { "$ref": "#/components/schemas/Judgment" } } }, "example": { "judgments": [ { "candidate_id": "tt0111161", "grade": 4, "member_id": "01JRVX6GG4XMSM55XBC3E518E0", "user_name": "alice" }, { "candidate_id": "tt0068646", "grade": 3, "ai_judge_id": "01JRVX6GG4XMSM55XBC3E518E1", "ai_judge_name": "Claude Judge", "reasoning": "The candidate's title and overview closely match the query intent." } ] } }, "ListMembersResponse": { "required": [ "members", "page", "page_size", "total_count", "total_pages" ], "type": "object", "properties": { "members": { "type": "array", "items": { "$ref": "#/components/schemas/MemberResponse" }, "description": "The collection of members on the current page." }, "page": { "type": "integer", "description": "The page number (1-based)", "format": "int32", "example": 1 }, "page_size": { "type": "integer", "description": "The page size", "format": "int32", "example": 20 }, "total_count": { "type": "integer", "description": "The total count of items", "format": "int32", "example": 42 }, "total_pages": { "type": "integer", "description": "The total number of pages given the total count and page size", "format": "int32", "example": 3 } }, "example": { "members": [ { "picture": "https://www.gravatar.com/avatar/5658ffccee7f0ebfda2b226238b1eb6e", "name": "Example Member", "username": "member@example.com", "id": "01JRVX6GG4XMSM55XBC3E518DY", "roles": [ "Admin" ], "status": "active" } ], "page": 1, "page_size": 20, "total_count": 1, "total_pages": 1 } }, "ListMetricsResponse": { "required": [ "metrics" ], "type": "object", "properties": { "metrics": { "type": "array", "items": { "$ref": "#/components/schemas/MetricDescription" }, "description": "The available evaluation metrics." } }, "example": { "metrics": [ { "name": "P@k", "description": "Precision at K", "default_k": 10 }, { "name": "R@k", "description": "Recall at K", "default_k": 10 }, { "name": "F1@k", "description": "F1 Score at K. The F-Score balances precision and recall using a harmonic mean.", "default_k": 10 }, { "name": "MAP", "description": "Mean Average Precision computes the mean of the Average Precision across multiple queries and their results." }, { "name": "ERR@k", "description": "Expected Reciprocal Rank at k", "default_k": 10 }, { "name": "MRR@k", "description": "Mean Reciprocal Rank measures how early the first relevant result appears in a ranked list.", "default_k": 10 }, { "name": "DCG@k", "description": "Discounted Cumulative Gain measures the gain of the top K results whilst also considering the rank/position of results in the ranked list", "default_k": 10 }, { "name": "NDCG@k", "description": "Normalized Discounted Cumulative Gain measures the gain of the top K results whilst also considering the rank/position of results in the ranked list, normalized by the ideal gain", "default_k": 10 }, { "name": "Best@k", "description": "Best relevance grade within top K results", "default_k": 10 } ] } }, "ListQuerySetsResponse": { "required": [ "query_sets" ], "type": "object", "properties": { "query_sets": { "type": "array", "items": { "$ref": "#/components/schemas/QuerySetResponse" }, "description": "A collection of query sets" } }, "example": { "query_sets": [ { "id": "01JRVX6GG4XMSM55XBC3E518DY", "name": "Movies", "description": "Movies from TMDB", "member_id": "01JRVX6GG4XMSM55XBC3E518E2", "created": "2026-05-13T10:30:00+00:00", "format": "json" }, { "id": "01JRVX6GG4XMSM55XBC3E518F4", "name": "Music", "description": "Music tracks from MusicBrainz", "member_id": "01JRVX6GG4XMSM55XBC3E518E2", "created": "2026-05-14T11:00:00+00:00", "format": "json" } ] } }, "ListQueryTemplatesResponse": { "required": [ "query_templates" ], "type": "object", "properties": { "query_templates": { "type": "array", "items": { "$ref": "#/components/schemas/QueryTemplateResponse" }, "description": "A collection of query templates" } }, "example": { "query_templates": [ { "id": "01JRVX6GG4XMSM55XBC3E518DY", "content_type": "json", "body": "{ \"query\": { \"match\": { \"title\": \"{{query}}\" } } }", "query_string": "?size={{size}}", "name": "Multi-match query", "member_id": "01JRVX6GG4XMSM55XBC3E518E2", "created": "2026-05-13T10:30:00+00:00" } ] } }, "ListQueryTemplatesTestResponse": { "required": [ "query_templates", "format" ], "type": "object", "properties": { "query_templates": { "type": "array", "items": { "$ref": "#/components/schemas/QueryTemplateTestResponse" }, "description": "A collection of outputs from executing a query template on a query set." }, "format": { "type": "string", "description": "The format of the queries in the query set provided.", "example": "json" } }, "example": { "query_templates": [ { "query": "Shrek", "query_string": "?size=10", "body": "{ \"query\": { \"match\": { \"title\": \"Shrek\" } } }" } ], "format": "json" } }, "ListTablesResponse": { "required": [ "tables" ], "type": "object", "properties": { "tables": { "type": "array", "items": { "$ref": "#/components/schemas/TableInfo" }, "description": "The tables available for querying." } }, "description": "A response listing the available User Behavior Insights ClickHouse tables.", "example": { "tables": [ { "name": "events", "engine": "MergeTree", "total_rows": 1500, "total_bytes": 204800, "partition_key": "toYYYYMM(timestamp)", "sorting_key": "timestamp", "primary_key": "timestamp" }, { "name": "queries", "engine": "MergeTree", "total_rows": 850, "total_bytes": 102400, "partition_key": "toYYYYMM(timestamp)", "sorting_key": "timestamp", "primary_key": "timestamp" } ] } }, "ListWorkspaceTabsResponse": { "required": [ "tabs" ], "type": "object", "properties": { "tabs": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceTabResponse" }, "description": "The list of workspace tabs." } }, "description": "A response containing a list of workspace tabs.", "example": { "tabs": [ { "id": "01JRVX6GG4XMSM55XBC3E518DY", "name": "Recent clicks", "content": "SELECT * FROM events WHERE action_name = 'click' LIMIT 100" }, { "id": "01JRVX6GG4XMSM55XBC3E518EZ", "name": "Top queries", "content": "SELECT user_query, count() AS hits FROM queries GROUP BY user_query ORDER BY hits DESC LIMIT 20" } ] } }, "LoginRequest": { "required": [ "email", "password" ], "type": "object", "properties": { "email": { "type": "string", "description": "The member's email address which acts as a member name.", "example": "member@example.com" }, "password": { "type": "string", "description": "The member's password.", "example": "S3cur3P@ssw0rd!" }, "two_factor_code": { "type": [ "null", "string" ], "description": "The optional two-factor authenticator code. This may be required for members who have enabled two-factor authentication.\n This is not required if a two-factor recovery code is sent.", "example": 123456 }, "two_factor_recovery_code": { "type": [ "null", "string" ], "description": "An optional two-factor recovery code.\n This is required for members who have enabled two-factor authentication but lost access to\n their two-factor code.", "example": "a1b2c3d4" } } }, "MemberResponse": { "required": [ "username", "id" ], "type": "object", "properties": { "picture": { "type": [ "null", "string" ], "description": "The profile picture, if available", "example": "https://www.gravatar.com/avatar/5658ffccee7f0ebfda2b226238b1eb6e" }, "name": { "type": [ "null", "string" ], "description": "The member's name", "example": "Example Member" }, "username": { "type": "string", "description": "The username", "example": "member@example.com" }, "id": { "type": "string", "description": "The member id", "example": "01JRVX6GG4XMSM55XBC3E518DY" }, "roles": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "The member roles, if available", "example": [ "Admin" ] }, "archived": { "type": [ "null", "string" ], "description": "Whether the member is archived, if available", "format": "date-time", "example": "2026-05-13T10:30:00Z" }, "status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MemberStatus" } ] } } }, "MemberStatus": { "enum": [ "active", "invited", "archived", null ], "description": "The member's status, if available", "example": "active" }, "Meta": { "required": [ "name", "type" ], "type": "object", "properties": { "name": { "type": "string", "description": "The name of the column.", "example": "action_name" }, "type": { "type": "string", "description": "The data type of the column.", "example": "String" } }, "description": "Meta-information about columns returned by a query." }, "MetricBucket": { "required": [ "name", "bucket_start", "bucket_count" ], "type": "object", "properties": { "name": { "type": "string", "description": "The metric name", "example": "NDCG" }, "bucket_start": { "type": "number", "description": "The bucket start value", "format": "double", "example": 0 }, "bucket_count": { "type": "number", "description": "The number of values that fall into this bucket.", "format": "double", "example": 10 } } }, "MetricComparisonItem": { "required": [ "name" ], "type": "object", "properties": { "name": { "type": "string", "description": "The name of the metric.", "example": "NDCG@10" }, "run_value": { "type": [ "null", "number" ], "description": "The metric value for the run being compared.", "format": "double", "example": 0.872 }, "baseline_value": { "type": [ "null", "number" ], "description": "The metric value for the baseline run.", "format": "double", "example": 0.847 }, "delta": { "type": [ "null", "number" ], "description": "The absolute difference between the run value and the baseline value.", "format": "double", "example": 0.025 }, "relative_delta": { "type": [ "null", "number" ], "description": "The relative difference between the run value and the baseline value, expressed as a ratio.", "format": "double", "example": 0.0295 } } }, "MetricDescription": { "required": [ "name", "description" ], "type": "object", "properties": { "name": { "type": "string", "description": "The name of the metric", "example": "NDCG" }, "description": { "type": "string", "description": "The description for the metric", "example": "Normalized Discounted Cumulative Gain measures ranking quality using graded relevance." }, "default_k": { "type": [ "null", "integer" ], "description": "If the metric is concerned with evaluation depth, the default k value used.", "format": "int32", "example": 10 } } }, "MetricStatistics": { "required": [ "name", "count", "count_one", "count_zero", "mean", "variance", "standard_deviation", "kurtosis", "skewness" ], "type": "object", "properties": { "name": { "type": "string", "description": "The name of the metric", "example": "NDCG" }, "count": { "type": "integer", "description": "The count of metric instances", "format": "int32", "example": 100 }, "count_one": { "type": "integer", "description": "The count of metric instances with a value of 1.", "format": "int32", "example": 25 }, "count_zero": { "type": "integer", "description": "The count of metric instances with a value of 0.", "format": "int32", "example": 10 }, "mean": { "type": "number", "description": "The mean metric value.", "format": "double", "example": 0.75 }, "variance": { "type": "number", "description": "The metric value variance", "format": "double", "example": 0.05 }, "standard_deviation": { "type": "number", "description": "The metric value standard deviation.", "format": "double", "example": 0.22 }, "kurtosis": { "type": "number", "description": "The metric value kurtosis.", "format": "double", "example": 2.5 }, "skewness": { "type": "number", "description": "The metric value skewness.", "format": "double", "example": 0.1 } } }, "MetricTrendRunResponse": { "required": [ "run_id", "run_name", "created", "status", "metrics", "config_changed" ], "type": "object", "properties": { "run_id": { "type": "string", "description": "The unique identifier of the evaluation run.", "example": "01JRVX6GG4XMSM55XBC3E518DY" }, "run_name": { "type": "string", "description": "The name of the evaluation run.", "example": "Movies baseline run" }, "created": { "type": "string", "description": "The datetime at which the evaluation run was created.", "format": "date-time", "example": "2026-05-13T10:30:00Z" }, "status": { "type": "string", "description": "The status of the evaluation run.", "example": "completed" }, "metrics": { "type": "object", "additionalProperties": { "type": [ "null", "number" ], "format": "double" }, "description": "The metric values for the run, keyed by metric name.", "example": { "NDCG@10": 0.847, "MAP": 0.612 } }, "config_changed": { "type": "boolean", "description": "Whether the run configuration changed relative to the previous run.", "example": true }, "config_changes": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "A list of configuration changes relative to the previous run.", "example": [ "body template changed", "headers changed" ] } } }, "MetricTrendsResponse": { "required": [ "runs", "metrics" ], "type": "object", "properties": { "runs": { "type": "array", "items": { "$ref": "#/components/schemas/MetricTrendRunResponse" }, "description": "The collection of evaluation runs with their metric values for trend analysis." }, "metrics": { "type": "array", "items": { "type": "string" }, "description": "The names of the metrics included in the trend data.", "example": [ "NDCG@10", "MAP", "MRR@10" ] } }, "example": { "runs": [ { "run_id": "01JRVX6GG4XMSM55XBC3E518DY", "run_name": "Movies baseline run", "created": "2026-05-13T10:30:00+00:00", "status": "completed", "metrics": { "NDCG@10": 0.847, "MAP": 0.612, "MRR@10": 0.755 }, "config_changed": false }, { "run_id": "01JRVX6GG4XMSM55XBC3E518E2", "run_name": "Movies tuned run", "created": "2026-05-14T10:30:00+00:00", "status": "completed", "metrics": { "NDCG@10": 0.872, "MAP": 0.645, "MRR@10": 0.781 }, "config_changed": true, "config_changes": [ "body template changed" ] } ], "metrics": [ "NDCG@10", "MAP", "MRR@10" ] } }, "NextResultForEvaluationResponse": { "required": [ "scale", "remaining_count", "total_count" ], "type": "object", "properties": { "result": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EvaluationQueryResultResponse" } ] }, "query": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EvaluationQueryForEvaluationResponse" } ] }, "scale": { "description": "The relevance scale used for the evaluation.", "$ref": "#/components/schemas/EvaluationScale" }, "remaining_count": { "type": "integer", "description": "The number of results remaining to be rated by the current member.", "format": "int32", "example": 42 }, "total_count": { "type": "integer", "description": "The total number of results in the evaluation run.", "format": "int32", "example": 250 }, "run_id": { "type": [ "null", "string" ], "description": "The evaluation run ID. Populated when results come from cross-run queries.", "example": "01JRVX6GG4XMSM55XBC3E518DY" }, "run_name": { "type": [ "null", "string" ], "description": "The evaluation run name. Populated when results come from cross-run queries.", "example": "Movies baseline run" }, "evaluation_name": { "type": [ "null", "string" ], "description": "The evaluation name. Populated when results come from cross-run queries.", "example": "Movies relevance evaluation" }, "corpus_id": { "type": [ "null", "string" ], "description": "The corpus ID for the evaluation's endpoint.", "example": "01JRVX6GG4XMSM55XBC3E518DZ" }, "oid": { "type": [ "null", "string" ], "description": "The query object hash for corpus-scoped judgment lookups.", "example": 67890 } }, "description": "Response containing the next result for evaluation by the current member.", "example": { "result": { "id": "01JRVX6GG4XMSM55XBC3E518R1", "position": 1, "evaluation_query_id": "01JRVX6GG4XMSM55XBC3E518DB", "created": "2026-05-13T10:30:00+00:00", "candidate": { "id": "tt0126029", "title": "Shrek", "fields": { "year": 2001 } } }, "query": { "id": "01JRVX6GG4XMSM55XBC3E518DB", "query": { "query": "Shrek" } }, "scale": "graded", "remaining_count": 42, "total_count": 250, "run_id": "01JRVX6GG4XMSM55XBC3E518DY", "run_name": "Movies baseline run", "evaluation_name": "Movies relevance evaluation", "corpus_id": "01JRVX6GG4XMSM55XBC3E518DZ", "oid": "67890" } }, "ObjectDetails": { "type": "object", "properties": { "object_id": { "type": [ "null", "string" ], "description": "The id that a user could look up and find the object instance within the *document corpus*.\n Examples include: _ssn_, _isbn_, _ean_, etc. Variants need to be incorporated in the object_id,\n so for a t-shirt that is red, you would need SKU level as the object_id.", "example": "sku-1234" }, "object_id_type": { "type": [ "null", "string" ], "description": "The type of the object id that the user is searching for. For a social e-commerce site,\n these could include product, user, post, comment, and so on.", "example": "product" }, "object_id_field": { "type": [ "null", "string" ], "description": "The name of the field that has the id of the objects that will be stored in the backend queries data store.\n So it you have a query for products and want to save the SKUs, then this might be sku and if you are\n querying for people, maybe this is ssn. If you do not provide this value then the default primary\n identifier in your search index will be used. For example _id on OpenSearch.", "example": "sku" }, "internal_id": { "type": [ "null", "string" ], "description": "A unique id that an individual search engine uses internally to index the object via.\n For example, for Elasticsearch and OpenSearch, this may be the _id field in the indices.", "example": "_id" } }, "description": "Structure which contains identifying information of the object returned from the query that the\n user interacts with (i.e.: a book, a product, a post, etc...)." }, "Position": { "type": "object", "properties": { "ordinal": { "type": [ "null", "integer" ], "description": "The nth position of the document on the search results page.", "format": "int32", "example": 1 }, "x": { "type": [ "null", "number" ], "description": "The horizontal location on the page or screen of the event.", "format": "double", "example": 400 }, "y": { "type": [ "null", "number" ], "description": "The vertical location on the page or screen of the event.", "format": "double", "example": 300 } }, "description": "Structure that contains information on the location of the event origin, such as screen x,y\n coordinates, or the nth object out of 10 results." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": [ "null", "string" ], "description": "A URI reference that identifies the problem type." }, "title": { "type": [ "null", "string" ], "description": "A short, human-readable summary of the problem type." }, "status": { "type": [ "null", "integer" ], "description": "The HTTP status code generated by the origin server for this occurrence of the problem.", "format": "int32" }, "detail": { "type": [ "null", "string" ], "description": "A human-readable explanation specific to this occurrence of the problem." }, "instance": { "type": [ "null", "string" ], "description": "A URI reference that identifies the specific occurrence of the problem." } }, "description": "A machine-readable format for specifying errors in HTTP API responses. See [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457)." }, "Query": { "oneOf": [ { "title": "String", "type": "string", "description": "A query text" }, { "title": "JSON Object", "type": "object", "additionalProperties": {}, "description": "A JSON object with a `\"query\"` string property and other properties." } ], "description": "A query, which can be either a string, or a JSON object with a \"query\" string property and other properties." }, "QueryAnalysis": { "required": [ "name", "baseline" ], "type": "object", "properties": { "name": { "type": "string", "description": "The name of the query in the analysis", "example": "Shrek" }, "baseline": { "type": "boolean", "description": "Whether this query is the baseline", "example": true }, "mean_duration_ms": { "type": "number", "description": "The mean duration in milliseconds of queries with the given name", "format": "double", "example": 45.6 } } }, "QueryComparisonItem": { "required": [ "query_item_id", "query", "run_metrics", "baseline_metrics", "status" ], "type": "object", "properties": { "query_item_id": { "type": "string", "description": "The unique identifier of the query from the query set.", "example": 12345 }, "query": { "$ref": "#/components/schemas/Query" }, "run_metrics": { "type": "object", "additionalProperties": { "type": [ "null", "number" ], "format": "double" }, "description": "The metric values for the query in the run being compared.", "example": { "NDCG@10": 0.872, "MAP": 0.645 } }, "baseline_metrics": { "type": "object", "additionalProperties": { "type": [ "null", "number" ], "format": "double" }, "description": "The metric values for the query in the baseline run.", "example": { "NDCG@10": 0.847, "MAP": 0.612 } }, "status": { "type": "string", "description": "The change status for the query relative to the baseline.", "example": "improved" } } }, "QueryIdResponse": { "required": [ "qid", "oid" ], "type": "object", "properties": { "qid": { "type": "string", "description": "The query ID." }, "oid": { "type": "string", "description": "The query object ID. When the query is a string, this is the same value as qid. When the query\n is a JSON object, the value is the hash of the query object JSON string." } } }, "QueryItemResponse": { "required": [ "query", "qid", "oid" ], "type": "object", "properties": { "query": { "$ref": "#/components/schemas/Query" }, "qid": { "type": "string", "description": "The query ID. A hash of the query text, or a member-provided value.", "example": 12345 }, "oid": { "type": "string", "description": "The query object ID. A hash of the complete query object, or a member-provided value.\n When the query is a string, this is the same value as qid.", "example": 67890 } } }, "QueryRequest": { "required": [ "query" ], "type": "object", "properties": { "query": { "type": "string", "description": "The query to execute. The query must be a valid single\n [ClickHouse SQL statement](https://clickhouse.com/docs/sql-reference)", "example": "SELECT * FROM ubi_events LIMIT 10" } }, "description": "A request to execute a query." }, "QueryResponse": { "required": [ "meta", "data", "statistics" ], "type": "object", "properties": { "meta": { "type": "array", "items": { "$ref": "#/components/schemas/Meta" }, "description": "Meta-information about columns returned by a query." }, "data": { "type": "array", "description": "The data returned by the query." }, "rows": { "type": "integer", "description": "The number of rows returned by the query.", "format": "int64", "example": 1500 }, "statistics": { "description": "Statistics about the query.", "$ref": "#/components/schemas/Statistics" } }, "description": "A response from a query.", "example": { "meta": [ { "name": "action_name", "type": "String" }, { "name": "timestamp", "type": "DateTime64(3, 'UTC')" } ], "data": [ { "action_name": "click", "timestamp": "2026-05-13T10:30:00.000Z" }, { "action_name": "add_to_basket", "timestamp": "2026-05-13T10:31:12.000Z" } ], "rows": 1500, "statistics": { "bytes_read": 204800, "elapsed": 0.042, "rows_read": 1500 } } }, "QuerySetResponse": { "required": [ "id", "name" ], "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the query set", "example": "01JRVX6GG4XMSM55XBC3E518DY" }, "name": { "type": "string", "description": "The name of the query set", "example": "Movies" }, "description": { "type": [ "null", "string" ], "description": "A description for the query set", "example": "Movies from TMDB" }, "member_id": { "type": [ "null", "string" ], "description": "The unique identifier of the member who created the query set", "example": "01JRVX6GG4XMSM55XBC3E518E2" }, "created": { "type": "string", "description": "The datetime at which the query set was created", "format": "date-time", "example": "2026-05-13T10:30:00Z" }, "queries": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/QueryItemResponse" }, "description": "The queries in the query set. The request controls whether queries are included in the response." }, "format": { "type": [ "null", "string" ], "description": "The format of the queries in the query set.", "example": "json" } }, "example": { "id": "01JRW0C6HBJXTJKXZP6CZDNPZT", "name": "Movies", "description": "Movies from TMDB", "created": "2025-04-01T00:00:00+00:00", "queries": [ { "query": { "query": "Shrek" }, "qid": "12345", "oid": "67890" }, { "query": { "query": "The Godfather" }, "qid": "12346", "oid": "67891" }, { "query": { "query": "Forrest Gump" }, "qid": "12347", "oid": "67892" }, { "query": { "query": "The Matrix" }, "qid": "12348", "oid": "67893" }, { "query": { "query": "The Shawshank Redemption" }, "qid": "12349", "oid": "67894" } ], "format": "json" } }, "QueryTemplateContentType": { "enum": [ "json", "text", null ], "description": "The content type of the body. **Required** if a body is provided.", "example": "json" }, "QueryTemplateResponse": { "required": [ "id", "name" ], "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the query template.", "example": "01JPS1EHNB49QNT617Y67M14SN" }, "content_type": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/QueryTemplateContentType" } ] }, "body": { "type": [ "null", "string" ], "description": "A [Mustache](https://mustache.github.io/) / [Handlebars](https://handlebarsjs.com/) template for the request body of an HTTP request.", "example": { "query": { "match": { "title": "{{query}}" } } } }, "query_string": { "type": [ "null", "string" ], "description": "A [Mustache](https://mustache.github.io/) / [Handlebars](https://handlebarsjs.com/) template for the query string parameters of an HTTP request.", "example": "?size={{size}}" }, "headers": { "type": [ "null", "object" ], "additionalProperties": { "type": "string" }, "description": "A [Mustache](https://mustache.github.io/) / [Handlebars](https://handlebarsjs.com/) template for the HTTP headers of an HTTP request.", "example": { "X-Search-Tenant": "{{tenant}}" } }, "name": { "type": "string", "description": "The name of the query template.", "example": "match_title" }, "member_id": { "type": [ "null", "string" ], "description": "The unique identifier of the member who created the query template.", "example": "01JPS1EHNHZKXQWWMBVQS3TNMV" }, "created": { "type": "string", "description": "The datetime of when the query template was created.", "format": "date-time", "example": "2026-05-13T10:30:00Z" }, "updated": { "type": [ "null", "string" ], "description": "The datetime of when the query template was last updated.", "format": "date-time", "example": "2026-05-14T15:51:28.071Z" } }, "example": { "id": "01JRW1AXDZY6Z2QHSBK5EVKYHN", "content_type": "json", "body": "{ \"query\": { \"match\": { \"title\": \"{{query}}\" } } }", "query_string": "?size={{size}}", "name": "match_title", "created": "2025-04-01T00:00:00+00:00" } }, "QueryTemplateTestResponse": { "required": [ "query" ], "type": "object", "properties": { "query": { "$ref": "#/components/schemas/Query" }, "query_string": { "type": [ "null", "string" ], "description": "The output from the [Mustache](https://mustache.github.io/) / [Handlebars](https://handlebarsjs.com/) template for the query string parameters of an HTTP request.", "example": "?size=10" }, "body": { "type": [ "null", "string" ], "description": "The output from the [Mustache](https://mustache.github.io/) / [Handlebars](https://handlebarsjs.com/) template for the request body of an HTTP request.", "example": { "query": { "match": { "title": "Shrek" } } } }, "headers": { "type": [ "null", "object" ], "additionalProperties": { "type": "string" }, "description": "The output from the [Mustache](https://mustache.github.io/) / [Handlebars](https://handlebarsjs.com/) template for the HTTP headers of an HTTP request.", "example": { "X-Search-Tenant": "movies" } } }, "example": { "query": "Shrek", "query_string": "?size=10", "body": "{ \"query\": { \"match\": { \"title\": \"Shrek\" } } }" } }, "RegisterRequest": { "required": [ "email", "password" ], "type": "object", "properties": { "email": { "type": "string", "description": "The member's email address which acts as a member name.", "example": "member@example.com" }, "password": { "type": "string", "description": "The member's password.", "example": "S3cur3P@ssw0rd!" } } }, "RejectedLicenseResponse": { "required": [ "reason" ], "type": "object", "properties": { "tier": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LicenseTier" } ] }, "type": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LicenseType" } ] }, "licensee": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Licensee" } ] }, "expires_at": { "type": [ "null", "string" ], "description": "The expiration date of the rejected license, if it could be parsed.", "format": "date-time", "example": "2026-01-31T00:00:00Z" }, "was_expired": { "type": "boolean", "description": "Whether the rejected license was rejected specifically because it had expired.", "example": true }, "reason": { "type": "string", "description": "Human-readable reason the license was rejected.", "example": "License expired on 2026-01-31" } }, "description": "Details of an external license that the server attempted to apply but rejected. Non-null when\n is true; null when the server is running on a normally-configured license.", "example": { "tier": "team", "type": "trial", "licensee": { "name": "Acme Corporation", "email": "licensing@acme.com" }, "expires_at": "2026-01-31T00:00:00+00:00", "was_expired": true, "reason": "License expired on 2026-01-31" } }, "ResetPasswordRequest": { "required": [ "email", "code", "new_password" ], "type": "object", "properties": { "email": { "type": "string", "description": "The email address for the member requesting a password reset.", "example": "member@example.com" }, "code": { "type": "string", "description": "The code sent to the member's email to reset the password.", "example": "CfDJ8N3a9b8c7d6e5f4g3h2i1j0k" }, "new_password": { "type": "string", "description": "The new password the member with the given email should log in with. This will replace the previous password.", "example": "N3wS3cur3P@ssw0rd!" } } }, "ResourceLimitsResponse": { "required": [ "members", "endpoints", "query_sets", "query_templates", "evaluations", "judgment_lists", "app_clients" ], "type": "object", "properties": { "members": { "description": "Member usage and limits.", "$ref": "#/components/schemas/ResourceUsageResponse" }, "endpoints": { "description": "Member usage and limits.", "$ref": "#/components/schemas/ResourceUsageResponse" }, "query_sets": { "description": "Member usage and limits.", "$ref": "#/components/schemas/ResourceUsageResponse" }, "query_templates": { "description": "Member usage and limits.", "$ref": "#/components/schemas/ResourceUsageResponse" }, "evaluations": { "description": "Member usage and limits.", "$ref": "#/components/schemas/ResourceUsageResponse" }, "judgment_lists": { "description": "Member usage and limits.", "$ref": "#/components/schemas/ResourceUsageResponse" }, "app_clients": { "description": "Member usage and limits.", "$ref": "#/components/schemas/ResourceUsageResponse" } }, "description": "Response containing current resource usage and limits.", "example": { "members": { "current": 5, "max": 25, "limit_reached": false, "percent_used": 20 }, "endpoints": { "current": 3, "max": 25, "limit_reached": false, "percent_used": 12 }, "query_sets": { "current": 12, "limit_reached": false }, "query_templates": { "current": 8, "limit_reached": false }, "evaluations": { "current": 42, "limit_reached": false }, "judgment_lists": { "current": 6, "limit_reached": false }, "app_clients": { "current": 2, "max": 10, "limit_reached": false, "percent_used": 20 } } }, "ResourceUsageResponse": { "type": "object", "properties": { "current": { "type": "integer", "description": "The current count of the resource.", "format": "int32", "example": 5 }, "max": { "type": [ "null", "integer" ], "description": "The maximum allowed count, or null if unlimited.", "format": "int32", "example": 25 }, "limit_reached": { "type": "boolean", "description": "Whether the limit has been reached.", "example": false }, "percent_used": { "type": [ "null", "integer" ], "description": "Percentage of limit used (0-100), or null if unlimited.", "format": "int32", "example": 20 } }, "description": "Member usage and limits." }, "RunComparisonResponse": { "required": [ "run_id", "baseline_run_id", "run_name", "baseline_name", "metrics_comparison", "query_comparisons", "summary", "page", "page_size", "total_count", "total_pages" ], "type": "object", "properties": { "run_id": { "type": "string", "description": "The unique identifier of the evaluation run being compared.", "example": "01JRVX6GG4XMSM55XBC3E518DY" }, "baseline_run_id": { "type": "string", "description": "The unique identifier of the baseline evaluation run for comparison.", "example": "01JRVX6GG4XMSM55XBC3E518D1" }, "run_name": { "type": "string", "description": "The name of the evaluation run being compared.", "example": "Movies tuned run" }, "baseline_name": { "type": "string", "description": "The name of the baseline evaluation run.", "example": "Movies baseline run" }, "metrics_comparison": { "type": "array", "items": { "$ref": "#/components/schemas/MetricComparisonItem" }, "description": "The per-metric comparison between the run and the baseline run." }, "query_comparisons": { "type": "array", "items": { "$ref": "#/components/schemas/QueryComparisonItem" }, "description": "The per-query comparison between the run and the baseline run." }, "summary": { "description": "A summary of how queries changed between the runs.", "$ref": "#/components/schemas/ComparisonSummary" }, "config_changes": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "A list of configuration changes between the run and the baseline run.", "example": [ "body template changed", "headers changed" ] }, "page": { "type": "integer", "description": "The page number (1-based).", "format": "int32", "example": 1 }, "page_size": { "type": "integer", "description": "The page size.", "format": "int32", "example": 50 }, "total_count": { "type": "integer", "description": "The total count of items.", "format": "int32", "example": 250 }, "total_pages": { "type": "integer", "description": "The total number of pages given the total count and page size.", "format": "int32", "example": 5 } }, "example": { "run_id": "01JRVX6GG4XMSM55XBC3E518DY", "baseline_run_id": "01JRVX6GG4XMSM55XBC3E518D1", "run_name": "Movies tuned run", "baseline_name": "Movies baseline run", "metrics_comparison": [ { "name": "NDCG@10", "run_value": 0.872, "baseline_value": 0.847, "delta": 0.025, "relative_delta": 0.0295 }, { "name": "MAP", "run_value": 0.645, "baseline_value": 0.612, "delta": 0.033, "relative_delta": 0.0539 } ], "query_comparisons": [ { "query_item_id": "12345", "query": { "query": "Shrek" }, "run_metrics": { "NDCG@10": 0.872, "MAP": 0.645 }, "baseline_metrics": { "NDCG@10": 0.847, "MAP": 0.612 }, "status": "improved" } ], "summary": { "improved": 42, "regressed": 15, "unchanged": 193 }, "config_changes": [ "body template changed" ], "page": 1, "page_size": 50, "total_count": 250, "total_pages": 5 } }, "StartAiJudgingRequest": { "required": [ "ai_judge_id" ], "type": "object", "properties": { "ai_judge_id": { "type": "string", "description": "The unique identifier of the AI judge to use.", "example": "01JRVX6GG4XMSM55XBC3E518DY" } } }, "Statistics": { "required": [ "bytes_read", "elapsed", "rows_read" ], "type": "object", "properties": { "bytes_read": { "type": "integer", "description": "The number of bytes read.", "format": "int64", "example": 204800 }, "elapsed": { "type": "number", "description": "The elapsed time in seconds.", "format": "double", "example": 0.042 }, "rows_read": { "type": "integer", "description": "The number of rows read.", "format": "int64", "example": 1500 } }, "description": "Statistics about the query." }, "SyncWorkspaceTabsRequest": { "required": [ "tabs" ], "type": "object", "properties": { "tabs": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceTabRequest" }, "description": "The list of tabs to sync. Tabs not in this list will be deleted." } }, "description": "A request to synchronize workspace tabs.", "example": { "tabs": [ { "id": "01JRVX6GG4XMSM55XBC3E518DY", "name": "Recent clicks", "content": "SELECT * FROM events WHERE action_name = 'click' LIMIT 100" }, { "id": "01JRVX6GG4XMSM55XBC3E518EZ", "name": "Top queries", "content": "SELECT user_query, count() AS hits FROM queries GROUP BY user_query ORDER BY hits DESC LIMIT 20" } ] } }, "TableDetails": { "required": [ "table", "columns", "create_table_query" ], "type": "object", "properties": { "table": { "description": "Summary information about a User Behavior Insights ClickHouse table.", "$ref": "#/components/schemas/TableInfo" }, "columns": { "type": "array", "items": { "$ref": "#/components/schemas/ColumnInfo" }, "description": "The columns of the table in declaration order." }, "create_table_query": { "type": "string", "description": "The CREATE TABLE DDL for the table.", "example": "CREATE TABLE events (timestamp DateTime64(3, 'UTC'), action_name String) ENGINE = MergeTree ORDER BY timestamp" } }, "description": "Full metadata for a single User Behavior Insights ClickHouse table.", "example": { "table": { "name": "events", "engine": "MergeTree", "total_rows": 1500, "total_bytes": 204800, "partition_key": "toYYYYMM(timestamp)", "sorting_key": "timestamp", "primary_key": "timestamp" }, "columns": [ { "name": "timestamp", "type": "DateTime64(3, 'UTC')", "default_expression": "now()", "comment": "The time at which the event occurred." }, { "name": "action_name", "type": "String", "comment": "The name of the action that triggered the event." } ], "create_table_query": "CREATE TABLE events (timestamp DateTime64(3, 'UTC'), action_name String) ENGINE = MergeTree ORDER BY timestamp" } }, "TableInfo": { "required": [ "name", "engine" ], "type": "object", "properties": { "name": { "type": "string", "description": "The name of the table.", "example": "events" }, "engine": { "type": "string", "description": "The ClickHouse storage engine the table uses.", "example": "MergeTree" }, "total_rows": { "type": "integer", "description": "The approximate number of rows stored in the table.", "format": "int64", "example": 1500 }, "total_bytes": { "type": "integer", "description": "The approximate number of bytes used by the table on disk.", "format": "int64", "example": 204800 }, "partition_key": { "type": [ "null", "string" ], "description": "The partitioning key expression, if any.", "example": "toYYYYMM(timestamp)" }, "sorting_key": { "type": [ "null", "string" ], "description": "The sorting key expression, if any.", "example": "timestamp" }, "primary_key": { "type": [ "null", "string" ], "description": "The primary key expression, if any.", "example": "timestamp" } }, "description": "Summary information about a User Behavior Insights ClickHouse table." }, "TestAiJudgeResponse": { "required": [ "success" ], "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the judge test succeeded.", "example": true }, "message": { "type": [ "null", "string" ], "description": "A human-readable message describing the outcome.", "example": "Judge connection succeeded." }, "response": { "type": [ "null", "string" ], "description": "The raw response returned by the judge model.", "example": { "score": 2, "rationale": "Highly relevant result." } } } }, "TestAiProviderRequest": { "required": [ "model" ], "type": "object", "properties": { "model": { "type": "string", "description": "The model identifier to test against (e.g. \"gpt-4o\", \"claude-sonnet-4-20250514\").", "example": "gpt-4o" } } }, "TestAiProviderResponse": { "required": [ "success" ], "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the connection test succeeded. true means the provider was reachable and\n the supplied credentials were accepted; false means the test failed — see\n for details.", "example": true }, "message": { "type": [ "null", "string" ], "description": "A human-readable message describing the outcome. On failure, contains the underlying\n error returned by the provider.", "example": "Provider connection succeeded." }, "response": { "type": [ "null", "string" ], "description": "The raw text returned by the model on a successful test, useful for verifying the\n model produced a sensible response.", "example": "Hello! How can I help you today?" } } }, "TestEndpointAuthRequest": { "required": [ "url", "type", "method" ], "type": "object", "properties": { "authentication": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AuthenticationCredentials" } ] }, "url": { "type": "string", "description": "The url of the endpoint.", "example": "https://localhost:9200/movies/_search" }, "type": { "$ref": "#/components/schemas/EndpointType" }, "method": { "type": "string", "description": "The HTTP method.\n The page endpoint type only supports the GET method.", "example": "GET" }, "body": { "type": [ "null", "string" ], "description": "The request body. When provided,\n a Content-Type header should be provided\n in the headers to indicate the content type of\n the body.", "example": { "query": { "match_all": {} } } }, "query_string": { "type": [ "null", "string" ], "description": "The query string parameters.", "example": "?size=10" }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The HTTP headers. Header names are case-insensitive", "example": { "Content-Type": "application/json" } }, "candidates_mapping": { "type": [ "null", "string" ], "description": "A [JMESPath](https://jmespath.org/) expression or JavaScript script to execute on the endpoint response\n that transforms it into a search result structure that Releval can consume.\n The page endpoint type supports a JavaScript script that executes in a browser context with the endpoint\n response and has access to the DOM and any other scripts loaded by the response. The script **must** transform\n the response into a JSON string search result structure.\n All other endpoint types support a JMESPath expression to transform the endpoint response into\n JSON search result structure.", "example": "{ total: (hits.total.value || hits.total), candidates: hits.hits[].{ id: _id, title: _source.title, image: _source.image, fields: _source } }" } } }, "TestEndpointRequest": { "type": "object", "properties": { "url": { "type": [ "null", "string" ], "description": "The url of the endpoint. If unspecified, uses the endpoint's existing url.", "example": "https://localhost:9200/movies/_search" }, "method": { "type": [ "null", "string" ], "description": "The HTTP method. If unspecified, uses the endpoint's existing HTTP method", "example": "GET" }, "body": { "type": [ "null", "string" ], "description": "The request body. When provided,\n a Content-Type header should be provided\n in the headers to indicate the content type of\n the body.", "example": { "query": { "match_all": {} } } }, "type": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EndpointType" } ] }, "query_string": { "type": [ "null", "string" ], "description": "The query string parameters.", "example": "?size=10" }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The HTTP headers. Header names are case-insensitive", "example": { "Content-Type": "application/json" } }, "candidates_mapping": { "type": [ "null", "string" ], "description": "A [JMESPath](https://jmespath.org/) expression or JavaScript script to execute on the endpoint response\n that transforms it into a search result structure that Releval can consume.\n The page endpoint type supports a JavaScript script that executes in a browser context with the endpoint\n response and has access to the DOM and any other scripts loaded by the response. The script **must** transform\n the response into a JSON string search result structure.\n All other endpoint types support a JMESPath expression to transform the endpoint response into\n JSON search result structure.\n If unspecified, uses the endpoint's existing candidates mapping.", "example": "{ total: (hits.total.value || hits.total), candidates: hits.hits[].{ id: _id, title: _source.title, image: _source.image, fields: _source } }" } } }, "TestQueryTemplateRequest": { "type": "object", "properties": { "query_string": { "type": [ "null", "string" ], "description": "A [Mustache](https://mustache.github.io/) / [Handlebars](https://handlebarsjs.com/) template for the\n query string parameters of an HTTP request. The template should form valid query string parameters for the\n target search endpoints it will be used with.", "example": "?size={{size}}" }, "body": { "type": [ "null", "string" ], "description": "A [Mustache](https://mustache.github.io/) / [Handlebars](https://handlebarsjs.com/) template for the request body of an HTTP request.\n The template should form a valid request body for the target search endpoints it will be used with.", "example": { "query": { "match": { "title": "{{query}}" } } } }, "content_type": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/QueryTemplateContentType" } ] }, "headers": { "type": [ "null", "object" ], "additionalProperties": { "type": "string" }, "description": "A [Mustache](https://mustache.github.io/) / [Handlebars](https://handlebarsjs.com/) template for the HTTP headers of an HTTP request.", "example": { "X-Search-Tenant": "{{tenant}}" } } } }, "TestQueryTemplateWithQueriesRequest": { "required": [ "queries" ], "type": "object", "properties": { "queries": { "maxItems": 5, "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/Query" }, "description": "An array of queries. All queries **must** be text or JSON objects, but not both." }, "query_string": { "type": [ "null", "string" ], "description": "A [Mustache](https://mustache.github.io/) / [Handlebars](https://handlebarsjs.com/) template for the\n query string parameters of an HTTP request. The template should form valid query string parameters for the\n target search endpoints it will be used with.", "example": "?size={{size}}" }, "body": { "type": [ "null", "string" ], "description": "A [Mustache](https://mustache.github.io/) / [Handlebars](https://handlebarsjs.com/) template for the request body of an HTTP request.\n The template should form a valid request body for the target search endpoints it will be used with.", "example": { "query": { "match": { "title": "{{query}}" } } } }, "content_type": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/QueryTemplateContentType" } ] }, "headers": { "type": [ "null", "object" ], "additionalProperties": { "type": "string" }, "description": "A [Mustache](https://mustache.github.io/) / [Handlebars](https://handlebarsjs.com/) template for the HTTP headers of an HTTP request.", "example": { "X-Search-Tenant": "{{tenant}}" } } }, "example": { "queries": [ "Shrek", "The Godfather" ], "query_string": "?size={{size}}", "body": "{ \"query\": { \"match\": { \"title\": \"{{query}}\" } } }", "content_type": "json" } }, "TrackEvent": { "required": [ "action_name", "timestamp" ], "type": "object", "properties": { "application": { "type": [ "null", "string" ], "description": "Name of the application sending data. You can think of application as a source of search queries.\n For example, if you have a type-ahead and a traditional search UI, then you might have type_ahead and primary_search as values.", "example": "primary_search" }, "action_name": { "type": "string", "description": "The name of the action that triggered the event e.g. click, add_to_basket, purchase.", "example": "click" }, "query_id": { "type": [ "null", "string" ], "description": "The unique identifier of a query, typically a [ULID](https://github.com/ulid/spec), but can be any string.", "example": "01JE0VDW4JV8XH1K2GDBZKXJXX" }, "session_id": { "type": [ "null", "string" ], "description": "The session of the user creating the interactions. This allows correlation of the interactions with other events created by a service that recognizes session IDs.\n Can be used to track unique visits for authenticated and anonymous users.", "example": "session_1" }, "client_id": { "type": [ "null", "string" ], "description": "The client issuing the query. This could be a unique browser, a microservice that performs searches, or a crawling bot.", "example": "search_service" }, "user_id": { "type": [ "null", "string" ], "description": "The user ID associated with the person performing the interactions being logged on the site. Can be null/empty in the case of an unauthenticated user.", "example": "user_1" }, "timestamp": { "description": "When the event took place. This timestamp is formatted according to the [ISO 8601 standard](https://en.wikipedia.org/wiki/ISO_8601).\n Timestamps should be sent in UTC by specifying Z as the offset.", "format": "date-time", "example": "2024-12-01T00:00:00.000Z" }, "message_type": { "type": [ "null", "string" ], "description": "Groups various action_names into logical bins.", "example": "QUERY" }, "message": { "type": [ "null", "string" ], "description": "Optional text message for the log entry. For example, for a message_type of query, we would expect\n the text to be about what the user is searching on.", "example": "warm clothes for winter" }, "user_query": { "type": [ "null", "string" ], "description": "The query as the user entered it. No length limit specified.", "example": "men's warm winter coat" }, "event_attributes": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EventAttributes" } ] } }, "description": "An event that occurred, typically in response to a user.", "example": { "application": "primary-search", "action_name": "click", "query_id": "01JE0VKZF8G03G7X16EDE6WNKJ", "session_id": "01JE0VM6029EVZT2SGHN1VYNAS", "client_id": "search_service", "timestamp": "2024-12-01T00:00:00.0000000Z", "user_query": "men's warm winter coat", "event_attributes": { "object": { "object_id": "sku001", "object_id_field": "sku" }, "position": { "ordinal": 1 } } } }, "TrackEventsRequest": { "required": [ "events" ], "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/TrackEvent" }, "description": "The events to track. At least one event must be provided." } }, "description": "A request to track one or more events." }, "TrackQueryRequest": { "required": [ "user_query" ], "type": "object", "properties": { "application": { "maxLength": 100, "type": [ "null", "string" ], "description": "Name of the application sending data. You can think of application as a source of search queries.\n For example, if you have a type-ahead and a traditional search UI, then you might have type_ahead and primary_search as values.", "example": "primary-search" }, "query_id": { "maxLength": 100, "type": [ "null", "string" ], "description": "The unique identifier of a query, typically a [ULID](https://github.com/ulid/spec), but can be any string.\n If unspecified, a unique id will be generated.", "example": "01JE0VKZF8G03G7X16EDE6WNKJ" }, "query_response_id": { "type": [ "null", "string" ], "description": "The unique identifier of a query response, typically a [ULID](https://github.com/ulid/spec), but can be any string.\n If unspecified, a unique id will be generated.", "example": "01JE0VM6029EVZT2SGHN1VYNAS" }, "query_response_hit_ids": { "type": "array", "items": { "type": "string" }, "description": "The ids of the documents that were returned by the search engine for this query in the order they were returned." }, "client_id": { "maxLength": 100, "type": [ "null", "string" ], "description": "The client issuing the query. This could be a unique browser, a microservice that performs searches, or a crawling bot.\n If only authenticated users are tracked, then you could use a specific user ID here. Otherwise, you should use something permanent and track user ID as an additional property.", "example": "search_service" }, "user_query": { "type": "string", "description": "The query as the user entered it. No length limit specified.", "example": "men's warm winter coat" }, "query_attributes": { "type": [ "null", "object" ], "description": "Any query modifiers like filter choices or pagination. Other attributes such as experiment identifiers that need to be tracked with the query." }, "object_id_field": { "maxLength": 100, "type": [ "null", "string" ], "description": "The name of the field that has the ID of the objects that will be stored in the backend queries data store.\n For example, if you have a query for products and want to save the SKUs, then this might be sku.\n If you are querying for people, maybe this is ssn.\n If you do not provide this value, then the default primary identifier in your search index will be used,\n such as _id in Elasticsearch and OpenSearch.", "example": "sku" }, "timestamp": { "description": "When the query was issued. This timestamp is formatted according to the [ISO 8601 standard](https://en.wikipedia.org/wiki/ISO_8601).\n Typically, the timestamp will be the time that the query was run.\n If you are replaying data or want to track the timezone of the caller specifically instead of using the\n search engine's timezone, you will need to provide the timestamp.\n Note: Timestamps should be sent in UTC by specifying Z as the offset.", "format": "date-time", "example": "2024-12-01T00:00:00.000Z" } }, "description": "Represents a query made by a user for UBI tracking.", "example": { "application": "primary-search", "query_id": "01JE0VKZF8G03G7X16EDE6WNKJ", "query_response_id": "01JE0VM6029EVZT2SGHN1VYNAS", "query_response_hit_ids": [ "sku001", "sku002", "sku003" ], "client_id": "search_service", "user_query": "men's warm winter coat", "query_attributes": { "experiment": "EXP001", "cohort": "A" }, "object_id_field": "sku", "timestamp": "2024-12-01T00:00:00.0000000Z" } }, "TrackQueryResponse": { "type": "object", "properties": { "query_id": { "type": "string", "description": "The unique identifier of a query, typically a [ULID](https://github.com/ulid/spec), but can be any string.", "example": "01JE0VKZF8G03G7X16EDE6WNKJ" }, "query_response_id": { "type": "string", "description": "The unique identifier of a query response, typically a [ULID](https://github.com/ulid/spec), but can be any string.\n If unspecified, a unique id will be generated.", "example": "01JE0VM6029EVZT2SGHN1VYNAS" } }, "description": "Represents the response to a query made by a user when using UBI." }, "UpdateAiJudgeRequest": { "required": [ "name", "ai_provider_id", "model", "prompt_template" ], "type": "object", "properties": { "name": { "type": "string", "description": "The name for the AI judge.", "example": "Relevance Judge" }, "description": { "type": [ "null", "string" ], "description": "A description for the AI judge.", "example": "Judges relevance of movie search results on a 0-4 scale." }, "ai_provider_id": { "type": "string", "description": "The configured AI provider this judge invokes. Set to a different provider id to relink.", "example": "01JRVX6GG4XMSM55XBC3E518DY" }, "model": { "type": "string", "description": "The model identifier.", "example": "gpt-4o" }, "prompt_template": { "type": "string", "description": "The Handlebars prompt template the judge sends to the model.", "example": "Rate the relevance of the result {{candidate.title}} for the query \"{{query}}\" on a scale of 0-4." }, "max_concurrency": { "type": [ "null", "integer" ], "description": "Maximum number of concurrent LLM requests during a judging run. Range: 1-50.", "format": "int32", "example": 5 }, "batch_size": { "type": [ "null", "integer" ], "description": "Number of candidates per prompt. Null or 1 means one candidate per LLM call. Range: 1-20.", "format": "int32", "example": 5 }, "include_images": { "type": [ "null", "boolean" ], "description": "Whether to include candidate images in the prompt. Requires a vision-capable model.", "example": false } } }, "UpdateAiProviderRequest": { "required": [ "type" ], "type": "object", "anyOf": [ { "$ref": "#/components/schemas/UpdateAiProviderRequestUpdateOpenAiProviderRequest" }, { "$ref": "#/components/schemas/UpdateAiProviderRequestUpdateAnthropicProviderRequest" }, { "$ref": "#/components/schemas/UpdateAiProviderRequestUpdateAzureOpenAiProviderRequest" }, { "$ref": "#/components/schemas/UpdateAiProviderRequestUpdateOllamaProviderRequest" }, { "$ref": "#/components/schemas/UpdateAiProviderRequestUpdateCustomProviderRequest" }, { "$ref": "#/components/schemas/UpdateAiProviderRequestUpdateAmazonBedrockProviderRequest" } ], "description": "Polymorphic update body for an AI provider. The discriminator type must match the\n existing provider's type — provider type is immutable post-creation. Secret fields are\n nullable: omitting (or sending null for) a secret keeps the existing value. Non-secret\n fields are wholesale-replaced.", "discriminator": { "propertyName": "type", "mapping": { "openai": "#/components/schemas/UpdateAiProviderRequestUpdateOpenAiProviderRequest", "anthropic": "#/components/schemas/UpdateAiProviderRequestUpdateAnthropicProviderRequest", "azure_openai": "#/components/schemas/UpdateAiProviderRequestUpdateAzureOpenAiProviderRequest", "ollama": "#/components/schemas/UpdateAiProviderRequestUpdateOllamaProviderRequest", "custom": "#/components/schemas/UpdateAiProviderRequestUpdateCustomProviderRequest", "amazon_bedrock": "#/components/schemas/UpdateAiProviderRequestUpdateAmazonBedrockProviderRequest" } } }, "UpdateAiProviderRequestUpdateAmazonBedrockProviderRequest": { "required": [ "aws_region", "access_key_id", "name" ], "properties": { "type": { "enum": [ "amazon_bedrock" ], "type": "string" }, "aws_region": { "type": "string", "description": "The AWS region in which Bedrock is provisioned. Required and wholesale-replaced.", "example": "us-east-1" }, "access_key_id": { "type": "string", "description": "The AWS access key ID. Required and wholesale-replaced.", "example": "AKIAIOSFODNN7EXAMPLE" }, "secret_access_key": { "type": [ "null", "string" ], "description": "The AWS secret access key. Omit or send null to keep the existing key; supplying a value rotates it.", "example": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" }, "name": { "type": "string", "description": "The provider's display name. Required and wholesale-replaced on every update.", "example": "OpenAI Production" } }, "description": "Update body for an Amazon Bedrock provider." }, "UpdateAiProviderRequestUpdateAnthropicProviderRequest": { "required": [ "name" ], "properties": { "type": { "enum": [ "anthropic" ], "type": "string" }, "api_key": { "type": [ "null", "string" ], "description": "The Anthropic API key. Omit or send null to keep the existing key; supplying a value rotates it.", "example": "sk-ant-api03-aBcDeFgHiJkLmNoPqRsTuVwXyZ" }, "name": { "type": "string", "description": "The provider's display name. Required and wholesale-replaced on every update.", "example": "OpenAI Production" } }, "description": "Update body for an Anthropic provider." }, "UpdateAiProviderRequestUpdateAzureOpenAiProviderRequest": { "required": [ "endpoint_url", "name" ], "properties": { "type": { "enum": [ "azure_openai" ], "type": "string" }, "endpoint_url": { "type": "string", "description": "The Azure OpenAI resource endpoint URL. Required and wholesale-replaced.", "example": "https://my-resource.openai.azure.com/" }, "api_key": { "type": [ "null", "string" ], "description": "The Azure OpenAI API key. Omit or send null to keep the existing key; supplying a value rotates it.", "example": "aBcDeFgHiJkLmNoPqRsTuVwXyZ1234567890" }, "name": { "type": "string", "description": "The provider's display name. Required and wholesale-replaced on every update.", "example": "OpenAI Production" } }, "description": "Update body for an Azure OpenAI provider." }, "UpdateAiProviderRequestUpdateCustomProviderRequest": { "required": [ "endpoint_url", "name" ], "properties": { "type": { "enum": [ "custom" ], "type": "string" }, "endpoint_url": { "type": "string", "description": "The endpoint URL of the OpenAI-compatible API. Required and wholesale-replaced.", "example": "https://llm.internal.example.com/v1/" }, "api_key": { "type": [ "null", "string" ], "description": "The optional API key. Omit or send null to keep the existing key; supplying a value rotates it.", "example": "sk-custom-aBcDeFgHiJkLmNoPqRsTuVwXyZ" }, "name": { "type": "string", "description": "The provider's display name. Required and wholesale-replaced on every update.", "example": "OpenAI Production" } }, "description": "Update body for a custom OpenAI-compatible provider." }, "UpdateAiProviderRequestUpdateOllamaProviderRequest": { "required": [ "endpoint_url", "name" ], "properties": { "type": { "enum": [ "ollama" ], "type": "string" }, "endpoint_url": { "type": "string", "description": "The Ollama server endpoint URL. Required and wholesale-replaced.", "example": "http://localhost:11434/" }, "name": { "type": "string", "description": "The provider's display name. Required and wholesale-replaced on every update.", "example": "OpenAI Production" } }, "description": "Update body for an Ollama provider." }, "UpdateAiProviderRequestUpdateOpenAiProviderRequest": { "required": [ "name" ], "properties": { "type": { "enum": [ "openai" ], "type": "string" }, "api_key": { "type": [ "null", "string" ], "description": "The OpenAI API key. Omit or send null to keep the existing key; supplying a value rotates it.", "example": "sk-proj-aBcDeFgHiJkLmNoPqRsTuVwXyZ" }, "name": { "type": "string", "description": "The provider's display name. Required and wholesale-replaced on every update.", "example": "OpenAI Production" } }, "description": "Update body for an OpenAI provider." }, "UpdateCorpusRequest": { "required": [ "name" ], "type": "object", "properties": { "name": { "type": "string", "description": "The name of the corpus.", "example": "Movies" }, "description": { "type": [ "null", "string" ], "description": "An optional description of the corpus.", "example": "Movies from TMDB" } } }, "UpdateEndpointRequest": { "required": [ "name", "type", "url", "method", "candidates_mapping" ], "type": "object", "properties": { "name": { "type": "string", "description": "A name for the endpoint.", "example": "Movies" }, "description": { "type": [ "null", "string" ], "description": "A description for the endpoint.", "example": "Movies from TMDB" }, "type": { "$ref": "#/components/schemas/EndpointType" }, "url": { "type": "string", "description": "The url of the endpoint.", "example": "https://localhost:9200/movies/_search" }, "method": { "type": "string", "description": "The HTTP method.\n The page endpoint type only supports the GET method.", "example": "GET" }, "candidates_mapping": { "type": "string", "description": "A [JMESPath](https://jmespath.org/) expression or JavaScript script to execute on the endpoint response\n that transforms it into a search result structure that Releval can consume.\n The page endpoint type supports a JavaScript script that executes in a browser context with the endpoint\n response and has access to the DOM and any other scripts loaded by the response. The script **must** transform\n the response into a JSON string search result structure.\n All other endpoint types support a JMESPath expression to transform the endpoint response into\n JSON search result structure.", "example": "{ total: (hits.total.value || hits.total), candidates: hits.hits[].{ id: _id, title: _source.title, image: _source.image, fields: _source } }" } }, "example": { "name": "Movies", "description": "Movies from TMDB", "type": "elasticsearch", "url": "https://localhost:9200/movies/_search", "method": "GET", "candidates_mapping": "{ total: (hits.total.value || hits.total), candidates: hits.hits[].{ id: _id, title: _source.title, image: _source.image, fields: _source } }" } }, "UpdateEvaluationRequest": { "required": [ "name", "endpoint_id", "query_template_id", "query_set_id" ], "type": "object", "properties": { "name": { "type": "string", "description": "The name for the evaluation.", "example": "Popular Movies" }, "description": { "type": [ "null", "string" ], "description": "A description for the evaluation.", "example": "Popular movies in the last week" }, "endpoint_id": { "type": "string", "description": "The unique identifier of the endpoint to use for evaluation.", "example": "01JRVX6GG4XMSM55XBC3E518DY" }, "query_template_id": { "type": "string", "description": "The unique identifier of the query template to use for evaluation.", "example": "01JRVX6GG4XMSM55XBC3E518E3" }, "query_set_id": { "type": "string", "description": "The unique identifier of the query set to use for evaluation.", "example": "01JRVX6GG4XMSM55XBC3E518E2" } } }, "UpdateEvaluationRunTagsRequest": { "required": [ "tags" ], "type": "object", "properties": { "tags": { "type": "array", "items": { "type": "string" }, "description": "The tags to set on the evaluation run. Pass an empty list to clear all tags.", "example": [ "commit:abc123", "staging", "experiment-v2" ] } } }, "UpdatePasswordRequest": { "required": [ "current_password", "new_password" ], "type": "object", "properties": { "current_password": { "type": "string", "description": "The member's current password", "example": "S3cur3P@ssw0rd!" }, "new_password": { "type": "string", "description": "The new password the member should log in with. This will replace the current password.", "example": "N3wS3cur3P@ssw0rd!" } } }, "UpdateQueryTemplateRequest": { "required": [ "name" ], "type": "object", "properties": { "query_string": { "type": [ "null", "string" ], "description": "A [Mustache](https://mustache.github.io/) / [Handlebars](https://handlebarsjs.com/) template for the\n query string parameters of an HTTP request. The template should form valid query string parameters for the\n target search endpoints it will be used with.", "example": "?size={{size}}" }, "content_type": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/QueryTemplateContentType" } ] }, "body": { "type": [ "null", "string" ], "description": "A [Mustache](https://mustache.github.io/) / [Handlebars](https://handlebarsjs.com/) template for the request body of an HTTP request.\n The template should form a valid request body for the target search endpoints it will be used with.", "example": { "query": { "match": { "title": "{{query}}" } } } }, "name": { "type": "string", "description": "A name for the query template.\n We recommend using a convention that clearly distinguishes templates from one another.", "example": "Multi-match query" }, "headers": { "type": [ "null", "object" ], "additionalProperties": { "type": "string" }, "description": "A [Mustache](https://mustache.github.io/) / [Handlebars](https://handlebarsjs.com/) template for the HTTP headers of an HTTP request.", "example": { "X-Search-Tenant": "{{tenant}}" } } } }, "UpsertJudgmentItem": { "required": [ "query", "candidate_id", "grade" ], "type": "object", "properties": { "query": { "$ref": "#/components/schemas/Query" }, "candidate_id": { "type": "string", "description": "The identifier of the candidate to provide a judgment for", "example": "tt0111161" }, "grade": { "type": "integer", "description": "The grade to assign to the candidate. Must be within the range of the specified scale.", "format": "int32", "example": 3 }, "evaluation_query_id": { "type": [ "null", "string" ], "description": "Optional provenance link to a specific evaluation query within a run", "example": "01JRVX6GG4XMSM55XBC3E518E2" } }, "description": "A single judgment to upsert" }, "UpsertJudgmentsRequest": { "required": [ "corpus_id", "scale", "judgments" ], "type": "object", "properties": { "corpus_id": { "type": "string", "description": "The unique identifier of the corpus (document collection) for these judgments", "example": "01JRVX6GG4XMSM55XBC3E518DZ" }, "scale": { "$ref": "#/components/schemas/EvaluationScale" }, "judgments": { "maxItems": 100, "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/UpsertJudgmentItem" }, "description": "The judgments to create or update" } }, "example": { "corpus_id": "01JRVX6GG4XMSM55XBC3E518DZ", "scale": "graded", "judgments": [ { "query": { "query": "Shrek" }, "candidate_id": "tt0126029", "grade": 4, "evaluation_query_id": "01JRVX6GG4XMSM55XBC3E518E2" }, { "query": { "query": "The Godfather" }, "candidate_id": "tt0068646", "grade": 3 } ] } }, "UpsertJudgmentsResponse": { "required": [ "judgments" ], "type": "object", "properties": { "judgments": { "type": "array", "items": { "$ref": "#/components/schemas/JudgmentResponse" } } }, "example": { "judgments": [ { "query_id": "01JRVX6GG4XMSM55XBC3E518E2", "grade": 4, "created": "2026-05-13T10:30:00+00:00", "member_id": "01JRVX6GG4XMSM55XBC3E518E0", "candidate_id": "tt0126029" }, { "grade": 3, "created": "2026-05-13T10:31:00+00:00", "updated": "2026-05-13T11:15:00+00:00", "candidate_id": "tt0068646", "ai_judge_id": "01JRVX6GG4XMSM55XBC3E518E1", "reasoning": "The candidate's title and overview closely match the query intent." } ] } }, "ValidationProblemDetails": { "type": "object", "properties": { "type": { "type": [ "null", "string" ], "description": "A URI reference that identifies the problem type." }, "title": { "type": [ "null", "string" ], "description": "A short, human-readable summary of the problem type." }, "status": { "type": [ "null", "integer" ], "description": "The HTTP status code generated by the origin server for this occurrence of the problem.", "format": "int32" }, "detail": { "type": [ "null", "string" ], "description": "A human-readable explanation specific to this occurrence of the problem." }, "instance": { "type": [ "null", "string" ], "description": "A URI reference that identifies the specific occurrence of the problem." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "A collection of errors keyed by the request parameter to which the errors relate. Errors that do not directly relate to a request parameter name are keyed by an empty string." } }, "description": "A machine-readable format for specifying errors in HTTP API responses that includes validation errors. See [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457).", "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "name": [ "name is required" ] } } }, "WorkspaceTabRequest": { "required": [ "id", "name" ], "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the tab.", "example": "01JRVX6GG4XMSM55XBC3E518DY" }, "name": { "type": "string", "description": "The name of the tab.", "example": "Recent clicks" }, "content": { "type": [ "null", "string" ], "description": "The SQL query content.", "example": "SELECT * FROM events WHERE action_name = 'click' LIMIT 100" } }, "description": "A workspace tab in a sync request." }, "WorkspaceTabResponse": { "required": [ "id", "name" ], "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the tab.", "example": "01JRVX6GG4XMSM55XBC3E518DY" }, "name": { "type": "string", "description": "The name of the tab.", "example": "Recent clicks" }, "content": { "type": [ "null", "string" ], "description": "The SQL query content.", "example": "SELECT * FROM events WHERE action_name = 'click' LIMIT 100" } }, "description": "A workspace tab response." } }, "securitySchemes": { "Bearer": { "type": "oauth2", "description": "OAuth2 Bearer tokens", "flows": { "clientCredentials": { "tokenUrl": "https://$\\{RELEVAL_HOST\\}/oauth2/token", "scopes": {} } } } } }, "tags": [ { "name": "Corpora", "description": "A Corpus represents a document collection that one or more\n[Search Endpoints](/docs/rest-api/search-endpoints) can target. Judgments and query sets are scoped to a\ncorpus so that relevance evaluations stay aligned with the documents they grade.\n\nA corpus cannot be deleted while it still has associated search endpoints.\n" }, { "name": "Search Endpoints", "description": "Search Endpoints define where Releval sends search queries for evaluation. Each endpoint represents a target \nsearch infrastructure such as [Elasticsearch](https://www.elastic.co/elasticsearch), [OpenSearch](https://opensearch.org/), \nor a generic HTTP-based Search API. Releval captures \nresponses from these endpoints to analyze results and compute relevancy metrics.\n\nEndpoints are configured with a base URL, HTTP method, endpoint type, and authentication method." }, { "name": "Query Sets", "description": "Query Sets are collections of queries that serve as input for search evaluations in Releval. Each set represents\nrealistic user search behavior and is used to assess the relevancy of your search implementation. Queries can be\nsimple strings or structured JSON objects containing search terms and optional metadata.\n\nQuery sets can be created via the Create Query Set API or uploaded using the Upload Query Set API, supporting queries\nas either strings or JSON. All queries within a set must share the same format— either all strings or all JSON\nobjects. When used with query templates, each query is rendered into a full search request, enabling consistent\ntesting across multiple configurations." }, { "name": "Query Templates", "description": "Query Templates in Releval define reusable, parameterized search requests using \n[Mustache](https://mustache.github.io/) / [Handlebars](https://handlebarsjs.com/) syntax.\nThey allow you to dynamically construct search queries by substituting variables into request bodies and query\nstrings. This enables consistent, flexible evaluation across varying query sets and configurations.\n\nTemplates support conditional logic, iteration, and raw JSON insertion via the `toJson` helper. When combined with\nquery sets, each query is rendered into a complete request, making it easy to test and compare different search\nstrategies. Templates can be tested via the Test Query Template API to validate output before full-scale evaluation." }, { "name": "Evaluations", "description": "Evaluations are the core mechanism in Releval for measuring search quality. An evaluation defines \nthe query set, query template, and endpoint to be used by an evaluation run. \n\nBy running evaluations, you can evaluate different configurations, detect regressions, and quantify the impact of\nchanges to ranking models, query logic, or indexing strategies over time." }, { "name": "Evaluation Runs", "description": "Evaluation Runs represent the execution of an evaluation at a specific point in time. \n\nAn evaluation run captures the full set of query executions, results, and metrics generated when an evaluation is run.\nEach run is tied to a particular evaluation configuration, enabling comparisons across runs. Runs provide the data \nneeded to analyze performance trends, validate changes, and support reproducible testing." }, { "name": "AI Providers", "description": "AI Providers hold the credentials and connection details for a large language model service\n(OpenAI, Anthropic, Azure OpenAI, Ollama, a custom OpenAI-compatible endpoint, or Amazon Bedrock).\nThe polymorphic `type` discriminator selects the shape; required fields vary per type.\n\nSecret fields are encrypted at rest and never returned by read endpoints. Providers are\nreferenced by [AI Judges](/docs/rest-api/ai-judges) and can be tested against a caller-specified model.\n" }, { "name": "AI Judges", "description": "AI Judges use large language models to grade search results, producing automated relevance\njudgments for an evaluation run. Each judge references an [AI Provider](/docs/rest-api/ai-providers) and\npairs it with a model identifier and a Handlebars prompt template.\n\nA judge can be tested for connectivity and then used to start an AI judging run against a\ncompleted evaluation run.\n" }, { "name": "App Clients", "description": "App Clients provide secure, programmatic access to Releval's APIs using [OAuth 2.0 authentication](https://www.oauth.com/). \n\nEach app client is issued a unique `client_id` and `client_secret` upon creation—credentials used to\nauthenticate requests from applications or services. App Clients are ideal for integrating Releval\ninto external systems or automation workflows." }, { "name": "Members", "description": "Members are the people authenticated into a Releval instance. (Not to be confused with end-users\ntracked under [User Behavior Insights](/docs/rest-api/user-behavior-insights).)\n\nAdmins can invite new members by email, archive and restore them, and resend invitations.\nNon-admins can list active members.\n" }, { "name": "Auth", "description": "Auth handles user registration and password management. New users can register with an email\nand password, after which they receive a confirmation email to verify their email address.\nPassword reset is available for users who have forgotten their credentials." }, { "name": "Accounts", "description": "Accounts provides authenticated users with access to their personal account information. It allows clients to\nretrieve key details about the currently signed-in user, including their user ID, email address, display name,\nusername, and email verification status." }, { "name": "Analysis", "description": "Analysis compares search results across different query configurations to measure overlap and performance.\nAn analysis executes queries against a search endpoint using one or more query templates, then computes\nmetrics such as [Rank Biased Overlap](https://doi.org/10.1145/1852102.1852106) and exact N-match overlap\nto quantify how similar the result sets are.\n\nAnalyses can be created by running queries against a live endpoint or by uploading a pre-existing\nquery executions file. Each analysis tracks execution progress and provides per-query statistical\nbreakdowns including mean, variance, skewness, and kurtosis of metric values." }, { "name": "Features", "description": "Features extract training data from judgment lists for use in learning-to-rank models. Given a judgment\nlist and a set of query templates, Releval executes feature extraction queries against the associated\nElasticsearch or OpenSearch endpoint to produce feature value vectors for each judged query-document pair." }, { "name": "Judgment Lists", "description": "Judgment Lists are collections of explicit relevance judgments that define the ground truth for\nsearch quality measurement. Each list contains query-document pairs with associated relevance grades,\nuploaded as a file in a supported format.\n\nJudgment lists are linked to a search endpoint and can be used to compute ranked retrieval metrics\nsuch as NDCG and MAP during evaluation runs, or to generate training data for learning-to-rank models." }, { "name": "Judgments", "description": "Judgments are individual relevance assessments for search results returned by an evaluation run.\nEach judgment assigns a grade to a specific candidate within a query's result set, based on the\nevaluation's grading scale.\n\nJudgments can be created manually by users or generated automatically by AI judges. When judgments\nare submitted, relevancy metrics for the affected queries are recalculated automatically.\n" }, { "name": "License", "description": "License provides information about the current Releval license including the tier, licensee,\nand expiration date. It also exposes resource usage limits, showing the current count and maximum\nallowed for each resource type such as users, endpoints, query sets, and evaluations." }, { "name": "User Behavior Insights", "description": "User Behavior Insights (UBI) captures client-side events and server-side queries for the purposes \nof improving search relevance and the user experience. It is a causal system, linking a user's query to all of their\nsubsequent interactions with your application until they perform another search.\n\n[User Behavior Insights is a standard open source format](https://www.ubisearch.dev/) to define and share\nuser event tracking information.\n\nUser Behavior Insights APIs are available as both REST and gRPC APIs. We recommend using the \n[gRPC APIs](/docs/api-concepts/grpc-api) for optimal performance in high-demand environments." } ] }