{ "components": { "schemas": { "AnswerJobCreated": { "description": "Response body for POST /v1/answers (HTTP 202).", "properties": { "job_id": { "title": "Job Id", "type": "string" }, "poll_url": { "description": "URL to poll for the result (GET, same API key).", "title": "Poll Url", "type": "string" }, "status": { "description": "Job status: queued, running, succeeded, failed.", "title": "Status", "type": "string" } }, "required": [ "job_id", "status", "poll_url" ], "title": "AnswerJobCreated", "type": "object" }, "AnswerJobResult": { "description": "Response body for GET /v1/answers/{job_id}.", "properties": { "answer": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The generated answer (Bulgarian), present when status is succeeded. Bracketed citation markers reference excerpt_id/document_id values from the sources list.", "title": "Answer" }, "completed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Completed At" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At" }, "error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Code" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Message" }, "job_id": { "title": "Job Id", "type": "string" }, "query": { "title": "Query", "type": "string" }, "sources": { "description": "Sources the answer is grounded in.", "items": { "$ref": "#/components/schemas/PublicSearchResult" }, "title": "Sources", "type": "array" }, "status": { "title": "Status", "type": "string" } }, "required": [ "job_id", "status", "query" ], "title": "AnswerJobResult", "type": "object" }, "ApiKeyCreateRequest": { "properties": { "name": { "description": "Human-readable label, e.g. 'production backend'.", "maxLength": 100, "minLength": 1, "title": "Name", "type": "string" } }, "required": [ "name" ], "title": "ApiKeyCreateRequest", "type": "object" }, "ApiKeyCreatedResponse": { "properties": { "api_key": { "description": "The full API key. Shown only once - store it securely; it cannot be retrieved again.", "title": "Api Key", "type": "string" }, "key_id": { "title": "Key Id", "type": "string" }, "key_prefix": { "title": "Key Prefix", "type": "string" }, "name": { "title": "Name", "type": "string" }, "tier": { "title": "Tier", "type": "string" } }, "required": [ "key_id", "name", "tier", "api_key", "key_prefix" ], "title": "ApiKeyCreatedResponse", "type": "object" }, "ApiKeyInfo": { "properties": { "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At" }, "key_id": { "title": "Key Id", "type": "string" }, "key_prefix": { "title": "Key Prefix", "type": "string" }, "last_used_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Used At" }, "name": { "title": "Name", "type": "string" }, "status": { "title": "Status", "type": "string" }, "tier": { "title": "Tier", "type": "string" } }, "required": [ "key_id", "name", "tier", "status", "key_prefix" ], "title": "ApiKeyInfo", "type": "object" }, "ApiKeysResponse": { "properties": { "keys": { "items": { "$ref": "#/components/schemas/ApiKeyInfo" }, "title": "Keys", "type": "array" } }, "required": [ "keys" ], "title": "ApiKeysResponse", "type": "object" }, "CourtInfo": { "properties": { "abbreviation": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Abbreviation" }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "City" }, "court_id": { "title": "Court Id", "type": "integer" }, "name": { "title": "Name", "type": "string" } }, "required": [ "court_id", "name" ], "title": "CourtInfo", "type": "object" }, "CourtsResponse": { "properties": { "courts": { "items": { "$ref": "#/components/schemas/CourtInfo" }, "title": "Courts", "type": "array" } }, "required": [ "courts" ], "title": "CourtsResponse", "type": "object" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "title": "Detail", "type": "array" } }, "title": "HTTPValidationError", "type": "object" }, "JudgeInfo": { "properties": { "decision_count": { "title": "Decision Count", "type": "integer" }, "name": { "title": "Name", "type": "string" } }, "required": [ "name", "decision_count" ], "title": "JudgeInfo", "type": "object" }, "JudgesResponse": { "properties": { "judges": { "items": { "$ref": "#/components/schemas/JudgeInfo" }, "title": "Judges", "type": "array" } }, "required": [ "judges" ], "title": "JudgesResponse", "type": "object" }, "PublicAnswerRequest": { "description": "Request body for POST /v1/answers.\n\nSame filters as POST /v1/search; the pipeline first searches, then\ngenerates a grounded Bulgarian answer citing the found sources.\n``include_content`` is ignored (answer jobs never store full document\nbodies; fetch them via GET /v1/documents).", "properties": { "court_ids": { "anyOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "description": "Restrict court case law to these court IDs (see GET /v1/catalog/courts). Only applies to court source families.", "title": "Court Ids" }, "date_from": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Only sources published on/after this date (YYYY-MM-DD).", "title": "Date From" }, "date_to": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Only sources published on/before this date (YYYY-MM-DD).", "title": "Date To" }, "include_content": { "default": false, "description": "Deprecated compatibility field. Full document text is never returned by search; use GET /v1/documents so retrieval quota is accounted for.", "title": "Include Content", "type": "boolean" }, "judge_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Restrict court case law to decisions involving this judge (fuzzy, case-insensitive match).", "title": "Judge Name" }, "max_results": { "default": 20, "description": "Maximum number of sources to return.", "maximum": 50.0, "minimum": 1.0, "title": "Max Results", "type": "integer" }, "query": { "description": "The legal question or search phrase, in Bulgarian for best results.", "maxLength": 2000, "minLength": 3, "title": "Query", "type": "string" }, "source_types": { "anyOf": [ { "items": { "enum": [ "bulgarian_laws_regulations", "eu_laws_regulations", "interpretative_court_decisions", "high_courts_cases", "low_courts_cases", "eu_caselaw", "mtsp_qa", "kzld", "patent_office", "kzk", "nap", "pms", "aop", "kzd", "cem", "bnb", "kfn", "kzp", "krs" ], "type": "string" }, "minItems": 1, "type": "array" }, { "type": "null" } ], "description": "Source families to search (see GET /v1/catalog/source-types). When omitted, the engine selects relevant families automatically.", "title": "Source Types" } }, "required": [ "query" ], "title": "PublicAnswerRequest", "type": "object" }, "PublicApiAccountResponse": { "properties": { "can_create_keys": { "title": "Can Create Keys", "type": "boolean" }, "can_manage_billing": { "title": "Can Manage Billing", "type": "boolean" }, "can_subscribe_launch": { "title": "Can Subscribe Launch", "type": "boolean" }, "can_subscribe_scale": { "title": "Can Subscribe Scale", "type": "boolean" }, "currency": { "title": "Currency", "type": "string" }, "current_period_end": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Current Period End" }, "limits": { "$ref": "#/components/schemas/PublicApiPlanLimits" }, "monthly_price": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Monthly Price" }, "overages": { "$ref": "#/components/schemas/PublicApiOverageSettings" }, "plan_name": { "title": "Plan Name", "type": "string" }, "status": { "title": "Status", "type": "string" }, "tier": { "title": "Tier", "type": "string" } }, "required": [ "plan_name", "tier", "status", "currency", "can_create_keys", "can_manage_billing", "can_subscribe_launch", "can_subscribe_scale", "limits", "overages" ], "title": "PublicApiAccountResponse", "type": "object" }, "PublicApiCheckoutCancelResponse": { "properties": { "cancelled": { "title": "Cancelled", "type": "boolean" } }, "required": [ "cancelled" ], "title": "PublicApiCheckoutCancelResponse", "type": "object" }, "PublicApiCheckoutRequest": { "properties": { "cancel_url": { "title": "Cancel Url", "type": "string" }, "promotion_code": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "description": "Optional customer-facing promotion code supplied by the Praven Intelekt team.", "title": "Promotion Code" }, "success_url": { "title": "Success Url", "type": "string" }, "tier": { "default": "launch", "description": "Self-service plan selected for the subscription.", "enum": [ "launch", "scale" ], "title": "Tier", "type": "string" } }, "required": [ "success_url", "cancel_url" ], "title": "PublicApiCheckoutRequest", "type": "object" }, "PublicApiCheckoutResponse": { "properties": { "checkout_url": { "title": "Checkout Url", "type": "string" }, "session_id": { "title": "Session Id", "type": "string" } }, "required": [ "checkout_url", "session_id" ], "title": "PublicApiCheckoutResponse", "type": "object" }, "PublicApiError": { "properties": { "detail": { "$ref": "#/components/schemas/PublicApiErrorDetail" } }, "required": [ "detail" ], "type": "object" }, "PublicApiErrorDetail": { "properties": { "code": { "description": "Stable machine-readable error code.", "examples": [ "rate_limit_exceeded" ], "type": "string" }, "message": { "description": "Human-readable English explanation.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "PublicApiInvoice": { "properties": { "amount_due": { "title": "Amount Due", "type": "integer" }, "amount_paid": { "title": "Amount Paid", "type": "integer" }, "created": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created" }, "currency": { "title": "Currency", "type": "string" }, "due_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Due Date" }, "hosted_invoice_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Hosted Invoice Url" }, "id": { "title": "Id", "type": "string" }, "invoice_pdf": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Invoice Pdf" }, "number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Number" }, "paid_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Paid At" }, "period_end": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Period End" }, "period_start": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Period Start" }, "status": { "title": "Status", "type": "string" } }, "required": [ "id", "status", "amount_due", "amount_paid", "currency" ], "title": "PublicApiInvoice", "type": "object" }, "PublicApiInvoicesResponse": { "properties": { "has_more": { "title": "Has More", "type": "boolean" }, "invoices": { "items": { "$ref": "#/components/schemas/PublicApiInvoice" }, "maxItems": 100, "title": "Invoices", "type": "array" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "required": [ "invoices", "has_more" ], "title": "PublicApiInvoicesResponse", "type": "object" }, "PublicApiOverageSettings": { "properties": { "currency": { "default": "EUR", "title": "Currency", "type": "string" }, "current_amount_cents": { "default": 0, "title": "Current Amount Cents", "type": "integer" }, "eligible": { "title": "Eligible", "type": "boolean" }, "enabled": { "title": "Enabled", "type": "boolean" }, "monthly_limit_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Monthly Limit Cents" }, "unit_prices_cents": { "$ref": "#/components/schemas/PublicApiOverageUnitPrices" } }, "required": [ "eligible", "enabled", "unit_prices_cents" ], "title": "PublicApiOverageSettings", "type": "object" }, "PublicApiOverageUnitPrices": { "properties": { "answer": { "title": "Answer", "type": "integer" }, "retrieval": { "title": "Retrieval", "type": "integer" }, "search": { "title": "Search", "type": "integer" } }, "required": [ "search", "retrieval", "answer" ], "title": "PublicApiOverageUnitPrices", "type": "object" }, "PublicApiOverageUpdateRequest": { "properties": { "enabled": { "title": "Enabled", "type": "boolean" }, "monthly_limit_cents": { "anyOf": [ { "maximum": 1000000.0, "minimum": 100.0, "type": "integer" }, { "type": "null" } ], "description": "Maximum additional monthly spend in euro cents. Required when enabling overages unless an existing limit is already stored.", "title": "Monthly Limit Cents" } }, "required": [ "enabled" ], "title": "PublicApiOverageUpdateRequest", "type": "object" }, "PublicApiPlanLimits": { "properties": { "active_keys": { "title": "Active Keys", "type": "integer" }, "answers": { "title": "Answers", "type": "integer" }, "requests_per_minute": { "title": "Requests Per Minute", "type": "integer" }, "retrievals": { "title": "Retrievals", "type": "integer" }, "searches": { "title": "Searches", "type": "integer" } }, "required": [ "searches", "retrievals", "answers", "requests_per_minute", "active_keys" ], "title": "PublicApiPlanLimits", "type": "object" }, "PublicApiPortalRequest": { "properties": { "return_url": { "title": "Return Url", "type": "string" } }, "required": [ "return_url" ], "title": "PublicApiPortalRequest", "type": "object" }, "PublicApiPortalResponse": { "properties": { "portal_url": { "title": "Portal Url", "type": "string" } }, "required": [ "portal_url" ], "title": "PublicApiPortalResponse", "type": "object" }, "PublicDocument": { "description": "Response body for GET /v1/documents.", "properties": { "author": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Author" }, "case_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Case Id" }, "collection": { "title": "Collection", "type": "string" }, "content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Content" }, "date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Date" }, "decision_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decision Number" }, "document_id": { "title": "Document Id", "type": "string" }, "elements": { "items": { "$ref": "#/components/schemas/PublicDocumentElement" }, "title": "Elements", "type": "array" }, "main_judge": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Main Judge" }, "participants": { "anyOf": [ {}, { "type": "null" } ], "title": "Participants" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary" }, "title": { "title": "Title", "type": "string" }, "type": { "title": "Type", "type": "string" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url" } }, "required": [ "document_id", "collection", "type", "title" ], "title": "PublicDocument", "type": "object" }, "PublicDocumentElement": { "description": "An ordered structural element of a document (article, paragraph).", "properties": { "content": { "title": "Content", "type": "string" }, "element_id": { "title": "Element Id", "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" } }, "required": [ "element_id", "content" ], "title": "PublicDocumentElement", "type": "object" }, "PublicExcerpt": { "description": "A relevant provision/paragraph inside a search result.", "properties": { "content": { "description": "Plain text of the provision.", "title": "Content", "type": "string" }, "excerpt_id": { "description": "Stable identifier of the provision/paragraph.", "title": "Excerpt Id", "type": "string" }, "relevance_score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Relevance score in [0, 1], higher is better.", "title": "Relevance Score" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Label of the provision, e.g. an article number.", "title": "Title" } }, "required": [ "excerpt_id", "content" ], "title": "PublicExcerpt", "type": "object" }, "PublicSearchRequest": { "description": "Request body for POST /v1/search.", "properties": { "court_ids": { "anyOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "description": "Restrict court case law to these court IDs (see GET /v1/catalog/courts). Only applies to court source families.", "title": "Court Ids" }, "date_from": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Only sources published on/after this date (YYYY-MM-DD).", "title": "Date From" }, "date_to": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Only sources published on/before this date (YYYY-MM-DD).", "title": "Date To" }, "include_content": { "default": false, "description": "Deprecated compatibility field. Full document text is never returned by search; use GET /v1/documents so retrieval quota is accounted for.", "title": "Include Content", "type": "boolean" }, "judge_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Restrict court case law to decisions involving this judge (fuzzy, case-insensitive match).", "title": "Judge Name" }, "max_results": { "default": 20, "description": "Maximum number of sources to return.", "maximum": 50.0, "minimum": 1.0, "title": "Max Results", "type": "integer" }, "query": { "description": "The legal question or search phrase, in Bulgarian for best results.", "maxLength": 2000, "minLength": 3, "title": "Query", "type": "string" }, "source_types": { "anyOf": [ { "items": { "enum": [ "bulgarian_laws_regulations", "eu_laws_regulations", "interpretative_court_decisions", "high_courts_cases", "low_courts_cases", "eu_caselaw", "mtsp_qa", "kzld", "patent_office", "kzk", "nap", "pms", "aop", "kzd", "cem", "bnb", "kfn", "kzp", "krs" ], "type": "string" }, "minItems": 1, "type": "array" }, { "type": "null" } ], "description": "Source families to search (see GET /v1/catalog/source-types). When omitted, the engine selects relevant families automatically.", "title": "Source Types" } }, "required": [ "query" ], "title": "PublicSearchRequest", "type": "object" }, "PublicSearchResponse": { "description": "Response body for POST /v1/search.", "properties": { "query": { "description": "The query as interpreted/executed.", "title": "Query", "type": "string" }, "result_count": { "title": "Result Count", "type": "integer" }, "results": { "items": { "$ref": "#/components/schemas/PublicSearchResult" }, "title": "Results", "type": "array" } }, "required": [ "query", "result_count", "results" ], "title": "PublicSearchResponse", "type": "object" }, "PublicSearchResult": { "description": "A single source returned by POST /v1/search.", "properties": { "author": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Issuing court/institution, if known.", "title": "Author" }, "case_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Case identifier for court decisions, if any.", "title": "Case Id" }, "collection": { "description": "Opaque collection token. Pass both collection and document_id to GET /v1/documents to fetch the full document.", "title": "Collection", "type": "string" }, "content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reserved for backwards compatibility and always null in search results. Use GET /v1/documents for full text.", "title": "Content" }, "date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Date" }, "decision_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decision Number" }, "document_id": { "title": "Document Id", "type": "string" }, "excerpts": { "items": { "$ref": "#/components/schemas/PublicExcerpt" }, "title": "Excerpts", "type": "array" }, "main_judge": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Main Judge" }, "relevance_explanation": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Short model-generated relevance rationale (Bulgarian).", "title": "Relevance Explanation" }, "relevance_score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Relevance score in [0, 1], higher is better.", "title": "Relevance Score" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "AI-generated summary of the document, if any.", "title": "Summary" }, "title": { "title": "Title", "type": "string" }, "type": { "description": "Document type label (Bulgarian, human-readable).", "title": "Type", "type": "string" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Canonical public URL of the source, if any.", "title": "Url" } }, "required": [ "document_id", "collection", "type", "title" ], "title": "PublicSearchResult", "type": "object" }, "QuotaStatus": { "properties": { "limit": { "title": "Limit", "type": "integer" }, "used": { "title": "Used", "type": "integer" } }, "required": [ "used", "limit" ], "title": "QuotaStatus", "type": "object" }, "SourceTypeInfo": { "properties": { "description": { "title": "Description", "type": "string" }, "source_type": { "title": "Source Type", "type": "string" }, "supports_court_filter": { "title": "Supports Court Filter", "type": "boolean" } }, "required": [ "source_type", "description", "supports_court_filter" ], "title": "SourceTypeInfo", "type": "object" }, "SourceTypesResponse": { "properties": { "source_types": { "items": { "$ref": "#/components/schemas/SourceTypeInfo" }, "title": "Source Types", "type": "array" } }, "required": [ "source_types" ], "title": "SourceTypesResponse", "type": "object" }, "UsageResponse": { "description": "Response body for GET /v1/usage.", "properties": { "answers": { "$ref": "#/components/schemas/QuotaStatus" }, "currency": { "default": "EUR", "title": "Currency", "type": "string" }, "overage_amount_cents": { "default": 0, "title": "Overage Amount Cents", "type": "integer" }, "period_month": { "description": "First day of the current UTC quota month.", "title": "Period Month", "type": "string" }, "requests_per_minute": { "title": "Requests Per Minute", "type": "integer" }, "retrievals": { "$ref": "#/components/schemas/QuotaStatus" }, "scope": { "default": "account", "description": "Allowances are pooled across every key on the account.", "title": "Scope", "type": "string" }, "searches": { "$ref": "#/components/schemas/QuotaStatus" }, "tier": { "title": "Tier", "type": "string" } }, "required": [ "tier", "period_month", "searches", "retrievals", "answers", "requests_per_minute" ], "title": "UsageResponse", "type": "object" }, "ValidationError": { "properties": { "ctx": { "title": "Context", "type": "object" }, "input": { "title": "Input" }, "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "title": "Location", "type": "array" }, "msg": { "title": "Message", "type": "string" }, "type": { "title": "Error Type", "type": "string" } }, "required": [ "loc", "msg", "type" ], "title": "ValidationError", "type": "object" } }, "securitySchemes": { "ApiKeyBearer": { "bearerFormat": "pi_live_…", "description": "Alternative API-key transport.", "scheme": "bearer", "type": "http" }, "ApiKeyHeader": { "description": "Recommended for server-to-server requests.", "in": "header", "name": "X-API-Key", "type": "apiKey" }, "UserBearer": { "bearerFormat": "Supabase JWT", "description": "Signed-in user token for developer billing and API-key management.", "scheme": "bearer", "type": "http" } } }, "externalDocs": { "description": "Developer guides", "url": "https://www.pravenintelekt.com/developers" }, "info": { "contact": { "email": "office@pravenintelekt.com", "name": "Praven Intelekt API support", "url": "https://www.pravenintelekt.com/contact" }, "description": "Search Bulgarian and EU legal sources, retrieve full documents, and create citation-grounded answers. The API is in limited beta; create a Praven Intelekt account to subscribe to Launch or contact us for a custom plan.", "license": { "name": "Commercial API terms", "url": "https://www.pravenintelekt.com/terms-of-service" }, "summary": "Programmatic Bulgarian legal research", "title": "Praven Intelekt API", "version": "1.0.0-beta.1" }, "openapi": "3.1.0", "paths": { "/v1/account": { "get": { "description": "Return the signed-in user's API plan and current entitlement.", "operationId": "getDeveloperAccount", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiAccountResponse" } } }, "description": "Successful Response" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" } } }, "description": "Machine-readable API error." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "UserBearer": [] } ], "summary": "Get the developer account", "tags": [ "Developer account" ] } }, "/v1/account/overages": { "patch": { "description": "Enable/disable paid usage and set an explicit monthly spend cap.", "operationId": "updateApiOverages", "requestBody": { "content": { "application/json": { "example": { "enabled": true, "monthly_limit_cents": 10000 }, "schema": { "$ref": "#/components/schemas/PublicApiOverageUpdateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiAccountResponse" } } }, "description": "Successful Response" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" } } }, "description": "Machine-readable API error." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "UserBearer": [] } ], "summary": "Configure paid API overages", "tags": [ "Developer account" ] } }, "/v1/answers": { "post": { "description": "Start an async answer job: search + grounded Bulgarian answer.\n\nReturns 202 with a job id immediately; poll GET /v1/answers/{job_id}\n(typically ready in 30-90 seconds). Counts against the monthly\nanswer quota; failed jobs are refunded.", "operationId": "createAnswer", "requestBody": { "content": { "application/json": { "example": { "max_results": 10, "query": "Може ли работодателят да прекрати трудов договор по време на отпуск?" }, "schema": { "$ref": "#/components/schemas/PublicAnswerRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnswerJobCreated" } } }, "description": "Successful Response" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" } } }, "description": "Machine-readable API error." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" } } }, "description": "Machine-readable API error." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" } } }, "description": "Machine-readable API error." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" } } }, "description": "Machine-readable API error." } }, "security": [ { "ApiKeyHeader": [] }, { "ApiKeyBearer": [] } ], "summary": "Create a grounded answer job", "tags": [ "Answers" ] } }, "/v1/answers/{job_id}": { "get": { "description": "Poll an answer job. Any key of the owning account may read it.", "operationId": "getAnswer", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "title": "Job Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnswerJobResult" } } }, "description": "Successful Response" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" } } }, "description": "Machine-readable API error." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" } } }, "description": "Machine-readable API error." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" } } }, "description": "Machine-readable API error." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" } } }, "description": "Machine-readable API error." } }, "security": [ { "ApiKeyHeader": [] }, { "ApiKeyBearer": [] } ], "summary": "Get an answer job", "tags": [ "Answers" ] } }, "/v1/billing/checkout": { "post": { "description": "Create a Stripe Checkout Session for a self-service API plan.", "operationId": "createApiCheckout", "requestBody": { "content": { "application/json": { "example": { "cancel_url": "https://app.pravenintelekt.com/api-access?checkout=cancelled", "success_url": "https://app.pravenintelekt.com/api-access?checkout=success" }, "schema": { "$ref": "#/components/schemas/PublicApiCheckoutRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiCheckoutResponse" } } }, "description": "Successful Response" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" } } }, "description": "Machine-readable API error." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" } } }, "description": "Machine-readable API error." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" } } }, "description": "Machine-readable API error." } }, "security": [ { "UserBearer": [] } ], "summary": "Start an API subscription checkout", "tags": [ "Developer account" ] } }, "/v1/billing/checkout/cancel": { "post": { "description": "Expire the signed-in user's abandoned API Checkout Session.", "operationId": "cancelApiCheckout", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiCheckoutCancelResponse" } } }, "description": "Successful Response" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" } } }, "description": "Machine-readable API error." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "UserBearer": [] } ], "summary": "Cancel a pending API checkout", "tags": [ "Developer account" ] } }, "/v1/billing/invoices": { "get": { "description": "List invoices for the signed-in user's API subscription.", "operationId": "listApiInvoices", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "starting_after", "required": false, "schema": { "anyOf": [ { "maxLength": 255, "pattern": "^in_[A-Za-z0-9]+$", "type": "string" }, { "type": "null" } ], "title": "Starting After" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiInvoicesResponse" } } }, "description": "Successful Response" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" } } }, "description": "Machine-readable API error." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" } } }, "description": "Machine-readable API error." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "UserBearer": [] } ], "summary": "List API subscription invoices", "tags": [ "Developer account" ] } }, "/v1/billing/portal": { "post": { "description": "Create a Stripe customer-portal session for API billing.", "operationId": "createApiBillingPortal", "requestBody": { "content": { "application/json": { "example": { "return_url": "https://app.pravenintelekt.com/api-access" }, "schema": { "$ref": "#/components/schemas/PublicApiPortalRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiPortalResponse" } } }, "description": "Successful Response" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" } } }, "description": "Machine-readable API error." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" } } }, "description": "Machine-readable API error." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "UserBearer": [] } ], "summary": "Manage API billing", "tags": [ "Developer account" ] } }, "/v1/catalog/courts": { "get": { "description": "List courts and their IDs for use in the court_ids search filter.", "operationId": "listCourts", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CourtsResponse" } } }, "description": "Successful Response" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" } } }, "description": "Machine-readable API error." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" } } }, "description": "Machine-readable API error." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" } } }, "description": "Machine-readable API error." } }, "security": [ { "ApiKeyHeader": [] }, { "ApiKeyBearer": [] } ], "summary": "List courts", "tags": [ "Catalog" ] } }, "/v1/catalog/judges": { "get": { "description": "List judges for a court (by court name), with optional name search.", "operationId": "listJudges", "parameters": [ { "in": "query", "name": "court", "required": true, "schema": { "title": "Court", "type": "string" } }, { "in": "query", "name": "search", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JudgesResponse" } } }, "description": "Successful Response" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" } } }, "description": "Machine-readable API error." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" } } }, "description": "Machine-readable API error." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" } } }, "description": "Machine-readable API error." } }, "security": [ { "ApiKeyHeader": [] }, { "ApiKeyBearer": [] } ], "summary": "List judges for a court", "tags": [ "Catalog" ] } }, "/v1/catalog/source-types": { "get": { "description": "List the searchable source families and their filter support.", "operationId": "listSourceTypes", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceTypesResponse" } } }, "description": "Successful Response" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" } } }, "description": "Machine-readable API error." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" } } }, "description": "Machine-readable API error." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" } } }, "description": "Machine-readable API error." } }, "security": [ { "ApiKeyHeader": [] }, { "ApiKeyBearer": [] } ], "summary": "List source types", "tags": [ "Catalog" ] } }, "/v1/documents": { "get": { "description": "Fetch a full document by (document_id, collection).\n\nBoth values come verbatim from a search result. Counts against the\nmonthly retrieval quota.", "operationId": "getDocument", "parameters": [ { "in": "query", "name": "document_id", "required": true, "schema": { "title": "Document Id", "type": "string" } }, { "in": "query", "name": "collection", "required": true, "schema": { "enum": [ "legal_documents", "court_decisions", "interpretative_court_decisions", "court_decisions_main", "eu_caselaw", "bg_mtsp_qa", "kzld_documents", "patent_documents", "kzk_documents", "nap_documents", "bg_sources.documents", "eu_sources.documents" ], "title": "Collection", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicDocument" } } }, "description": "Successful Response" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" } } }, "description": "Machine-readable API error." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" } } }, "description": "Machine-readable API error." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" } } }, "description": "Machine-readable API error." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" } } }, "description": "Machine-readable API error." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" } } }, "description": "Machine-readable API error." } }, "security": [ { "ApiKeyHeader": [] }, { "ApiKeyBearer": [] } ], "summary": "Retrieve a full document", "tags": [ "Documents" ] } }, "/v1/keys": { "get": { "description": "List the authenticated user's API keys (never the secrets).", "operationId": "listApiKeys", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeysResponse" } } }, "description": "Successful Response" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" } } }, "description": "Machine-readable API error." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "UserBearer": [] } ], "summary": "List API keys", "tags": [ "API keys" ] }, "post": { "description": "Create a new API key for the authenticated user.\n\nThe key inherits the active API account tier. A paid Launch account or\nan explicitly activated evaluation account is required.\nThe full key is returned only in this response.", "operationId": "createApiKey", "requestBody": { "content": { "application/json": { "example": { "name": "production backend" }, "schema": { "$ref": "#/components/schemas/ApiKeyCreateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreatedResponse" } } }, "description": "Successful Response" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" } } }, "description": "Machine-readable API error." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" } } }, "description": "Machine-readable API error." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" } } }, "description": "Machine-readable API error." } }, "security": [ { "UserBearer": [] } ], "summary": "Create an API key", "tags": [ "API keys" ] } }, "/v1/keys/{key_id}/revoke": { "post": { "description": "Revoke one of the authenticated user's API keys.", "operationId": "revokeApiKey", "parameters": [ { "in": "path", "name": "key_id", "required": true, "schema": { "title": "Key Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyInfo" } } }, "description": "Successful Response" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" } } }, "description": "Machine-readable API error." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" } } }, "description": "Machine-readable API error." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "UserBearer": [] } ], "summary": "Revoke an API key", "tags": [ "API keys" ] } }, "/v1/search": { "post": { "description": "Search Bulgarian and EU legal sources.\n\nRuns the full multi-stage legal search pipeline (query enhancement,\nparallel per-corpus retrieval, LLM relevance scoring and filtering)\nand returns ranked sources with their relevant provisions. Counts\nagainst the monthly search quota. Typical latency is 10-40 seconds\ndepending on corpus selection.", "operationId": "searchLegalSources", "requestBody": { "content": { "application/json": { "example": { "date_from": "2015-01-01", "include_content": false, "max_results": 10, "query": "Давностен срок при непозволено увреждане", "source_types": [ "bulgarian_laws_regulations", "high_courts_cases" ] }, "schema": { "$ref": "#/components/schemas/PublicSearchRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicSearchResponse" } } }, "description": "Successful Response" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" } } }, "description": "Machine-readable API error." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" } } }, "description": "Machine-readable API error." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" } } }, "description": "Machine-readable API error." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" } } }, "description": "Machine-readable API error." } }, "security": [ { "ApiKeyHeader": [] }, { "ApiKeyBearer": [] } ], "summary": "Search legal sources", "tags": [ "Search" ] } }, "/v1/usage": { "get": { "description": "Current-month pooled quota consumption for the calling account.", "operationId": "getUsage", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageResponse" } } }, "description": "Successful Response" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" } } }, "description": "Machine-readable API error." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" } } }, "description": "Machine-readable API error." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiError" } } }, "description": "Machine-readable API error." } }, "security": [ { "ApiKeyHeader": [] }, { "ApiKeyBearer": [] } ], "summary": "Get current usage", "tags": [ "Account" ] } } }, "servers": [ { "description": "Production (limited beta)", "url": "https://api.pravenintelekt.com" } ], "tags": [ { "description": "Search Bulgarian and EU legal sources.", "name": "Search" }, { "description": "Asynchronous, citation-grounded legal answers.", "name": "Answers" }, { "description": "Full-document retrieval from search results.", "name": "Documents" }, { "description": "Discover valid source and court filters.", "name": "Catalog" }, { "description": "Inspect pooled quota usage for the current account.", "name": "Account" }, { "description": "Inspect API access, subscribe to Launch, and manage billing with a signed-in Praven Intelekt user token.", "name": "Developer account" }, { "description": "Manage keys with a signed-in Praven Intelekt user token. These operations do not accept an API key.", "name": "API keys" } ] }