{"openapi":"3.1.0","info":{"title":"ADH Engine API","version":"2.41.16-32-g4bbaa3b","description":"Multi-provider data aggregation engine with intelligent provider selection, caching, and circuit breaker patterns."},"servers":[{"url":"https://4p1.io","description":"Production"}],"components":{"schemas":{"HealthResponse":{"type":"object","properties":{"status":{"type":"string","enum":["healthy","degraded","unhealthy"],"example":"healthy"},"version":{"type":"string","example":"1.0.0"},"runtime":{"type":"string","example":"cloudflare-workers"},"timestamp":{"type":"string","example":"2024-01-01T00:00:00.000Z"},"components":{"type":"object","properties":{"catalog":{"type":"object","properties":{"ok":{"type":"boolean"},"count":{"type":"number"},"error":{"type":"string"}},"required":["ok"],"description":"R2 catalog.json status"},"vectorize":{"type":"object","properties":{"ok":{"type":"boolean"},"count":{"type":"number"},"error":{"type":"string"}},"required":["ok"],"description":"Vectorize index status"},"cache":{"type":"object","properties":{"ok":{"type":"boolean"},"count":{"type":"number"},"error":{"type":"string"}},"required":["ok"],"description":"Redis cache status"},"database":{"type":"object","properties":{"ok":{"type":"boolean"},"count":{"type":"number"},"error":{"type":"string"}},"required":["ok"],"description":"D1 database status"}},"required":["catalog","vectorize","cache","database"]}},"required":["status","version","runtime","timestamp","components"]},"EngineError":{"type":"object","properties":{"code":{"type":"string","example":"NOT_FOUND"},"message":{"type":"string","example":"No data found for document"},"retryable":{"type":"boolean","default":false,"example":false}},"required":["code","message"]},"EngineResponse":{"type":"object","properties":{"requestId":{"type":"string","example":"019b25be-f5b1-77f7-985c-c2a3792722ce"},"success":{"type":"boolean","example":true},"data":{"type":"object","additionalProperties":{},"example":{"nome":"John Doe","situacao":"Regular"},"description":"Response data. For multi-query, namespaced by service: `{ 'cpf:basic': {...}, 'cpf:complete': {...} }`."},"providerCode":{"type":"string","example":"_m","description":"Query shape: `_m` (multi-query) or `_x` (cross-query); absent on single queries. Operator keys also receive the source of single queries."},"timestamp":{"type":"number","example":1702500000},"iC":{"type":"number","example":100,"description":"Information Cost in USD cents"},"pC":{"type":"number","example":10,"description":"Processing Cost in USD cents"},"latencyMs":{"type":"number","example":150},"cacheHit":{"type":"boolean","example":false},"error":{"$ref":"#/components/schemas/EngineError"}},"required":["requestId","success","timestamp","iC","pC","latencyMs","cacheHit"]},"EngineRequest":{"type":"object","properties":{"service":{"type":"string","minLength":1,"example":"cpf:basic","description":"Service to query. Formats: `service:endpoint` (single) or `service:endpoint,service:endpoint` (multi-query, max 5). Multi-query executes in parallel and returns namespaced results."},"document":{"type":"string","minLength":1,"example":"12345678900","description":"Query input document (CPF, CNPJ, CEP, etc.)"},"params":{"type":"object","additionalProperties":{"type":"string"},"example":{"moeda":"USD","data":"2024-01-15"},"description":"Additional query parameters"},"requestId":{"type":"string","example":"019b25be-f5b1-77f7-985c-c2a3792722ce","description":"Request ID for tracking (auto-generated if not provided)"}},"required":["service","document"]},"CatalogProviderSummary":{"type":"object","properties":{"code":{"type":"string","example":"adh"},"name":{"type":"string","example":"APIDevHub"},"type":{"type":"string","enum":["free","paid"],"example":"paid"},"servicesCount":{"type":"number","example":30},"endpointsCount":{"type":"number","example":12}},"required":["code","name","type","servicesCount","endpointsCount"]},"CatalogProvidersResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"providers":{"type":"array","items":{"$ref":"#/components/schemas/CatalogProviderSummary"}},"totalProviders":{"type":"number","example":1},"totalEndpoints":{"type":"number","example":89}},"required":["providers","totalProviders","totalEndpoints"]},"cacheHit":{"type":"boolean","example":false}},"required":["success","data","cacheHit"]},"CatalogErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string","example":"PROVIDER_NOT_FOUND"},"message":{"type":"string","example":"Provider not found: unknown"}},"required":["code","message"]}},"required":["success","error"]},"CatalogSearchResult":{"type":"object","properties":{"id":{"type":"string","example":"adh/cpf:basic"},"score":{"type":"number","example":0.92},"title":{"type":"string","example":"Consulta Basica de CPF"},"description":{"type":"string","example":"Dados basicos de pessoa fisica"},"provider":{"type":"string","example":"adh"},"service":{"type":"string","example":"cpf"},"endpoint":{"type":"string","example":"basic"},"pricing":{"type":"object","properties":{"iC":{"type":"number","example":200},"pC":{"type":"number","example":25},"totalCost":{"type":"number","example":225}},"required":["iC"]}},"required":["id","score","title","description","provider","service","endpoint","pricing"]},"CatalogSearchResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"query":{"type":"string","example":"validar cpf cliente"},"results":{"type":"array","items":{"$ref":"#/components/schemas/CatalogSearchResult"}},"totalResults":{"type":"number","example":5},"searchType":{"type":"string","enum":["fuzzy","semantic","keyword"],"example":"semantic"}},"required":["query","results","totalResults","searchType"]},"cacheHit":{"type":"boolean","example":false}},"required":["success","data","cacheHit"]},"CatalogServiceSummary":{"type":"object","properties":{"service":{"type":"string","example":"cpf"},"endpoints":{"type":"array","items":{"type":"string"},"example":["basic","complete"]},"endpointsCount":{"type":"number","example":4}},"required":["service","endpoints","endpointsCount"]},"CatalogProviderServicesResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"provider":{"$ref":"#/components/schemas/CatalogProviderSummary"},"services":{"type":"array","items":{"$ref":"#/components/schemas/CatalogServiceSummary"}}},"required":["provider","services"]},"cacheHit":{"type":"boolean","example":false}},"required":["success","data","cacheHit"]},"CatalogUseCase":{"type":"object","properties":{"industry":{"type":"string","example":"Financeiro"},"scenario":{"type":"string","example":"Onboarding de cliente"},"description":{"type":"string","example":"Validar identidade do cliente"}},"required":["industry","scenario","description"]},"CatalogEntry":{"type":"object","properties":{"id":{"type":"string","example":"adh/cpf:basic"},"provider":{"type":"object","properties":{"code":{"type":"string","example":"adh"},"name":{"type":"string","example":"APIDevHub"},"type":{"type":"string","enum":["free","paid"],"example":"paid"}},"required":["code","name","type"]},"service":{"type":"string","example":"cpf"},"endpoint":{"type":"string","example":"basic"},"title":{"type":"string","example":"Consulta Basica de CPF"},"description":{"type":"string","example":"Dados basicos de pessoa fisica"},"document":{"type":"object","properties":{"type":{"type":"string","example":"cpf"},"format":{"type":"string","example":"11 digitos"},"example":{"type":"string","example":"12345678900"}},"required":["type","format","example"]},"params":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"},"required":{"type":"boolean"},"description":{"type":"string"},"example":{"type":"string"}},"required":["name","type","required","description"]}},"responseFields":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"type":{"type":"string"},"description":{"type":"string"},"optional":{"type":"boolean"}},"required":["field","type","description"]}},"pricing":{"type":"object","properties":{"iC":{"type":"number","example":200},"pC":{"type":"number"},"totalCost":{"type":"number","example":225,"description":"Total cost (iC + pC)"},"currency":{"type":"string","example":"BRL"},"costDescription":{"type":"string","example":"200 iC (~R$ 12.00)"}},"required":["iC","currency","costDescription"]},"cache":{"type":"object","properties":{"enabled":{"type":"boolean"},"ttl":{"type":"string"}},"required":["enabled"],"description":"Cache configuration (TTL visible for HQ keys only)"},"useCases":{"type":"array","items":{"$ref":"#/components/schemas/CatalogUseCase"}},"keywords":{"type":"array","items":{"type":"string"}},"queriesThatShouldMatch":{"type":"array","items":{"type":"string"}},"relatedEndpoints":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"relation":{"type":"string"}},"required":["id","relation"]}},"limitations":{"type":"array","items":{"type":"string"}},"compliance":{"type":"object","properties":{"lgpd":{"type":"string"},"retention":{"type":"string"}}},"version":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","provider","service","endpoint","title","description","document","responseFields","pricing","useCases","keywords","queriesThatShouldMatch","version","updatedAt"]},"CatalogEndpointResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/CatalogEntry"},"cacheHit":{"type":"boolean","example":false}},"required":["success","data","cacheHit"]},"ValidationCodeResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"validationCode":{"type":"string","example":"01936a7e-8b4c-7d2f-9e1a-3c5b8d0f2e4a"},"expiresAt":{"type":"number","example":1705409460000}},"required":["success","validationCode","expiresAt"]},"CacheDeleteError":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string","example":"CACHE_ERROR"},"message":{"type":"string","example":"Failed to delete cache"}},"required":["code","message"]}},"required":["success","error"]},"CacheDeleteResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"pattern":{"type":"string","example":"adh:v1:provider-a:*"},"deleted":{"type":"number","example":42},"dryRun":{"type":"boolean","example":false}},"required":["success","pattern","deleted","dryRun"]},"ClearAllRequest":{"type":"object","properties":{"validationCode":{"type":"string","example":"01936a7e-8b4c-7d2f-9e1a-3c5b8d0f2e4a"}},"required":["validationCode"]},"ConfigInvalidateResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"target":{"type":"string","example":"all"},"invalidated":{"type":"boolean","enum":[true]}},"required":["success","target","invalidated"]},"User":{"type":"object","properties":{"id":{"type":"string","example":"01912345-6789-7abc-def0-123456789abc"},"email":{"type":"string","format":"email","example":"user@company.com"},"name":{"type":"string","example":"John Doe"},"company":{"type":["string","null"],"example":"ACME Corp"},"phone":{"type":["string","null"],"example":"+5511999999999"},"document":{"type":["string","null"],"example":"12345678000199"},"notes":{"type":["string","null"],"example":"VIP customer"},"active":{"type":"boolean","example":true},"createdAt":{"type":"string","example":"2024-01-15T10:30:00Z"},"updatedAt":{"type":"string","example":"2024-01-15T10:30:00Z"}},"required":["id","email","name","active"]},"UserCreatedResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/User"}},"required":["success","data"]},"UserError":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string","example":"VALIDATION_ERROR"},"message":{"type":"string","example":"Invalid email format"}},"required":["code","message"]}},"required":["success","error"]},"DuplicateEmailError":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string","enum":["DUPLICATE_EMAIL"]},"message":{"type":"string","enum":["Email already registered"]}},"required":["code","message"]}},"required":["success","error"]},"CreateUser":{"type":"object","properties":{"email":{"type":"string","format":"email","example":"user@company.com"},"name":{"type":"string","minLength":1,"example":"John Doe"},"company":{"type":"string","example":"ACME Corp"},"phone":{"type":"string","example":"+5511999999999"},"document":{"type":"string","example":"12345678000199"},"notes":{"type":"string","example":"VIP customer"}},"required":["email","name"]},"UserListResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"$ref":"#/components/schemas/User"}},"meta":{"type":"object","properties":{"total":{"type":"number","example":100},"limit":{"type":"number","example":50},"offset":{"type":"number","example":0},"hasMore":{"type":"boolean","example":true}},"required":["total","limit","offset","hasMore"]}},"required":["success","data","meta"]},"UserResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/User"}},"required":["success","data"]},"UpdateUser":{"type":"object","properties":{"email":{"type":"string","format":"email","example":"new-email@company.com"},"name":{"type":"string","minLength":1,"example":"John Updated"},"company":{"type":["string","null"],"example":"New Corp"},"phone":{"type":["string","null"],"example":"+5511888888888"},"document":{"type":["string","null"],"example":"98765432000199"},"notes":{"type":["string","null"],"example":"Updated notes"},"active":{"type":"boolean","example":false}}},"UserDeletedResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"message":{"type":"string","example":"User deactivated"}},"required":["success","message"]},"ApiKeyRole":{"type":"string","enum":["dev","prd","hq"],"example":"prd"},"ApiKeyPlan":{"type":"string","enum":["free","pro","enterprise"],"example":"free"},"ApiKeyCreated":{"type":"object","properties":{"id":{"type":"string","example":"01912345-6789-7abc-def0-123456789abc"},"key":{"type":"string","example":"adh_1a2b3c4d5e6f7g8h9i0j"},"prefix":{"type":"string","example":"adh_1a2b3c4d"},"role":{"$ref":"#/components/schemas/ApiKeyRole"},"plan":{"$ref":"#/components/schemas/ApiKeyPlan"},"rateLimit":{"type":"number","example":100},"createdAt":{"type":"string","example":"2024-01-15T10:30:00Z"}},"required":["id","key","prefix","role","plan","rateLimit","createdAt"]},"ApiKeyCreatedResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/ApiKeyCreated"},"warning":{"type":"string","enum":["Store this key securely. It will not be shown again."]}},"required":["success","data","warning"]},"ApiKeyError":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string","example":"VALIDATION_ERROR"},"message":{"type":"string","example":"Invalid user ID format"}},"required":["code","message"]}},"required":["success","error"]},"UserNotFoundError":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string","enum":["USER_NOT_FOUND"]},"message":{"type":"string","enum":["User not found"]}},"required":["code","message"]}},"required":["success","error"]},"CreateApiKey":{"type":"object","properties":{"userId":{"type":"string","example":"01912345-6789-7abc-def0-123456789abc"},"name":{"type":"string","example":"Production API Key"},"role":{"allOf":[{"$ref":"#/components/schemas/ApiKeyRole"},{"default":"prd"}]},"plan":{"allOf":[{"$ref":"#/components/schemas/ApiKeyPlan"},{"default":"free"}]},"rateLimit":{"type":"number","example":1000}},"required":["userId"]},"ApiKey":{"type":"object","properties":{"id":{"type":"string","example":"01912345-6789-7abc-def0-123456789abc"},"userId":{"type":"string","example":"01912345-6789-7abc-def0-123456789abc"},"prefix":{"type":"string","example":"adh_1a2b3c4d"},"name":{"type":["string","null"],"example":"Production API Key"},"role":{"$ref":"#/components/schemas/ApiKeyRole"},"plan":{"allOf":[{"$ref":"#/components/schemas/ApiKeyPlan"},{"example":"pro"}]},"rateLimit":{"type":"number","example":1000},"active":{"type":"boolean","example":true},"createdAt":{"type":"string","example":"2024-01-15T10:30:00Z"},"lastUsedAt":{"type":["string","null"],"example":"2024-01-15T12:00:00Z"},"revokedAt":{"type":["string","null"],"example":null},"updatedAt":{"type":"string","example":"2024-01-15T10:30:00Z"}},"required":["id","userId","prefix","role","plan","rateLimit","active"]},"ApiKeyListResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}},"meta":{"type":"object","properties":{"total":{"type":"number","example":100},"limit":{"type":"number","example":50},"offset":{"type":"number","example":0},"hasMore":{"type":"boolean","example":true}},"required":["total","limit","offset","hasMore"]}},"required":["success","data","meta"]},"ApiKeyResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/ApiKey"}},"required":["success","data"]},"UpdateApiKey":{"type":"object","properties":{"name":{"type":"string","example":"Updated Key Name"},"role":{"$ref":"#/components/schemas/ApiKeyRole"},"plan":{"allOf":[{"$ref":"#/components/schemas/ApiKeyPlan"},{"example":"pro"}]},"rateLimit":{"type":"number","example":2000},"active":{"type":"boolean","example":false}}},"ApiKeyDeletedResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"message":{"type":"string","example":"API key revoked"}},"required":["success","message"]},"ApiKeyRotatedResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/ApiKeyCreated"},"warning":{"type":"string","enum":["Store this key securely. It will not be shown again. The old key has been revoked."]}},"required":["success","data","warning"]},"RequestHistory":{"type":"object","properties":{"id":{"type":"string","example":"01912345-6789-7abc-def0-123456789abc"},"requestId":{"type":"string","example":"req_abc123"},"apiKeyHash":{"type":"string","example":"sha256..."},"userId":{"type":["string","null"],"example":"01912345-6789-7abc-def0-123456789abc"},"service":{"type":"string","example":"cpf"},"endpoint":{"type":"string","example":"basic"},"providerCode":{"type":["string","null"],"example":"provider-a"},"method":{"type":"string","example":"POST"},"path":{"type":"string","example":"/execute"},"success":{"type":"boolean","example":true},"statusCode":{"type":"number","example":200},"errorCode":{"type":["string","null"],"example":null},"informationCost":{"type":"number","example":10},"processingCost":{"type":"number","example":5},"latencyMs":{"type":"number","example":150},"cacheHit":{"type":"boolean","example":false},"requestTimestamp":{"type":"number","example":1705323000000},"createdAt":{"type":"string","example":"2024-01-15T10:30:00Z"},"updatedAt":{"type":"string","example":"2024-01-15T10:30:00Z"},"deletedAt":{"type":["string","null"],"example":null}},"required":["id","requestId","apiKeyHash","service","endpoint","method","path","success","statusCode","informationCost","processingCost","latencyMs","cacheHit","requestTimestamp"]},"RequestHistoryListResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"$ref":"#/components/schemas/RequestHistory"}},"meta":{"type":"object","properties":{"total":{"type":"number","example":1000},"limit":{"type":"number","example":100},"offset":{"type":"number","example":0},"hasMore":{"type":"boolean","example":true}},"required":["total","limit","offset","hasMore"]}},"required":["success","data","meta"]},"HistoryError":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string","example":"VALIDATION_ERROR"},"message":{"type":"string","example":"Invalid filter parameter"}},"required":["code","message"]}},"required":["success","error"]},"StoredPayload":{"type":"object","properties":{"requestId":{"type":"string","example":"req_abc123"},"timestamp":{"type":"number","example":1705323000000},"request":{"type":"object","properties":{"method":{"type":"string","example":"POST"},"path":{"type":"string","example":"/execute"},"headers":{"type":"object","additionalProperties":{"type":"string"},"example":{"Content-Type":"application/json"}},"body":{"example":{"service":"cpf:basic","document":"12345678900"}}},"required":["method","path","headers"]},"response":{"type":"object","properties":{"statusCode":{"type":"number","example":200},"headers":{"type":"object","additionalProperties":{"type":"string"},"example":{"Content-Type":"application/json"}},"body":{"example":{"success":true,"data":{}}}},"required":["statusCode","headers"]},"metadata":{"type":"object","properties":{"apiKeyHash":{"type":"string","example":"sha256..."},"userId":{"type":"string","example":"01912345-6789-7abc-def0-123456789abc"},"service":{"type":"string","example":"cpf"},"endpoint":{"type":"string","example":"basic"},"providerCode":{"type":"string","example":"provider-a"},"latencyMs":{"type":"number","example":150},"cacheHit":{"type":"boolean","example":false}},"required":["apiKeyHash","service","endpoint","latencyMs","cacheHit"]}},"required":["requestId","timestamp","request","response","metadata"]},"PayloadResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/StoredPayload"}},"required":["success","data"]},"R2NotConfiguredError":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string","enum":["R2_NOT_CONFIGURED"]},"message":{"type":"string","enum":["Payload storage not configured"]}},"required":["code","message"]}},"required":["success","error"]},"CostPeriod":{"type":"object","properties":{"period":{"type":"string","example":"2024-01-15"},"totalRequests":{"type":"number","example":100},"successfulRequests":{"type":"number","example":95},"failedRequests":{"type":"number","example":5},"cachedRequests":{"type":"number","example":30},"totalInformationCost":{"type":"number","example":1000},"totalProcessingCost":{"type":"number","example":500},"totalCost":{"type":"number","example":1500}},"required":["period","totalRequests","successfulRequests","failedRequests","cachedRequests","totalInformationCost","totalProcessingCost","totalCost"]},"BillingResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"apiKeyHash":{"type":"string","example":"sha256..."},"startDate":{"type":"number","example":1705323000000},"endDate":{"type":"number","example":1705409400000},"groupBy":{"type":"string","enum":["day","month"],"example":"day"},"periods":{"type":"array","items":{"$ref":"#/components/schemas/CostPeriod"}}},"required":["apiKeyHash","startDate","endDate","groupBy","periods"]}},"required":["success","data"]},"BillingError":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string","example":"VALIDATION_ERROR"},"message":{"type":"string","example":"api_key_hash is required"}},"required":["code","message"]}},"required":["success","error"]},"ServiceUsage":{"type":"object","properties":{"service":{"type":"string","example":"cpf"},"endpoint":{"type":"string","example":"basic"},"totalRequests":{"type":"number","example":50},"successfulRequests":{"type":"number","example":48},"cachedRequests":{"type":"number","example":15},"totalCost":{"type":"number","example":500}},"required":["service","endpoint","totalRequests","successfulRequests","cachedRequests","totalCost"]},"UsageResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"apiKeyHash":{"type":"string","example":"sha256..."},"startDate":{"type":"number","example":1705323000000},"endDate":{"type":"number","example":1705409400000},"services":{"type":"array","items":{"$ref":"#/components/schemas/ServiceUsage"}}},"required":["apiKeyHash","startDate","endDate","services"]}},"required":["success","data"]},"BillingSummaryResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"userId":{"type":"string","example":"user_123"},"startDate":{"type":"number","example":1705323000000},"endDate":{"type":"number","example":1705409400000},"creditBalance":{"type":"object","properties":{"available":{"type":"number","example":95000,"description":"Available credits (iC)"},"reserved":{"type":"number","example":500,"description":"Reserved credits (iC)"},"totalCredited":{"type":"number","example":100000,"description":"Lifetime credits received"},"totalDebited":{"type":"number","example":5000,"description":"Lifetime credits consumed"}},"required":["available","reserved","totalCredited","totalDebited"]},"periodUsage":{"type":"object","properties":{"totalRequests":{"type":"number","example":100},"successfulRequests":{"type":"number","example":95},"failedRequests":{"type":"number","example":5},"cachedRequests":{"type":"number","example":30},"totalCost":{"type":"number","example":1500,"description":"Total cost in iC for the period"}},"required":["totalRequests","successfulRequests","failedRequests","cachedRequests","totalCost"]}},"required":["userId","startDate","endDate","creditBalance","periodUsage"]}},"required":["success","data"]},"AddCreditsResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"balance":{"type":"number","example":100000},"package":{"type":"object","properties":{"id":{"type":"string","example":"01234567-89ab-cdef-0123-456789abcdef"},"amount":{"type":"number","example":100000},"expiresAt":{"type":"string","example":"2026-07-22T00:00:00Z"}},"required":["id","amount","expiresAt"]}},"required":["balance","package"]}},"required":["success","data"]},"CreditsError":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string","example":"INSUFFICIENT_CREDITS"},"message":{"type":"string","example":"Insufficient credits for this request"}},"required":["code","message"]}},"required":["success","error"]},"AddCreditsRequest":{"type":"object","properties":{"amount":{"type":"number","exclusiveMinimum":0,"example":100000,"description":"Amount in iC (1 iC = $0.0001 USD)"},"description":{"type":"string","example":"Initial credits package","description":"Reason for adding credits"},"expiresAt":{"type":"string","format":"date-time","example":"2026-07-22T00:00:00Z","description":"Custom expiration (default: 6 months)"}},"required":["amount"]},"BalanceResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"userId":{"type":"string","example":"user_123"},"availableBalance":{"type":"number","example":95000,"description":"iC available"},"reservedBalance":{"type":"number","example":500,"description":"iC reserved for pending requests"},"totalCredited":{"type":"number","example":100000,"description":"Lifetime credits received"},"totalDebited":{"type":"number","example":5000,"description":"Lifetime credits consumed"}},"required":["userId","availableBalance","reservedBalance","totalCredited","totalDebited"]}},"required":["success","data"]},"Package":{"type":"object","properties":{"id":{"type":"string","example":"pkg_123"},"originalAmount":{"type":"number","example":100000},"remainingAmount":{"type":"number","example":95000},"expiresAt":{"type":"string","example":"2026-07-22T00:00:00Z"},"expired":{"type":"boolean","example":false},"createdAt":{"type":"string","example":"2026-01-22T00:00:00Z"}},"required":["id","originalAmount","remainingAmount","expiresAt","expired","createdAt"]},"PackagesResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"userId":{"type":"string"},"packages":{"type":"array","items":{"$ref":"#/components/schemas/Package"}},"total":{"type":"number"}},"required":["userId","packages","total"]}},"required":["success","data"]},"Transaction":{"type":"object","properties":{"id":{"type":"string","example":"txn_123"},"type":{"type":"string","enum":["credit","debit","reserve","confirm","release","expire","adjustment","alert"],"example":"credit"},"amount":{"type":"number","example":-500,"description":"Positive=credit, negative=debit"},"balanceAfter":{"type":"number","example":95000},"description":{"type":["string","null"],"example":"Request cpf:basic"},"createdAt":{"type":"string","example":"2026-01-22T12:00:00Z"}},"required":["id","type","amount","balanceAfter","description","createdAt"]},"TransactionsResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"userId":{"type":"string"},"transactions":{"type":"array","items":{"$ref":"#/components/schemas/Transaction"}},"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"},"hasMore":{"type":"boolean"}},"required":["userId","transactions","total","limit","offset","hasMore"]}},"required":["success","data"]},"AdjustmentResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"previousBalance":{"type":"number","example":95000},"adjustment":{"type":"number","example":5000},"newBalance":{"type":"number","example":100000},"transactionId":{"type":"string","example":"txn_456"}},"required":["previousBalance","adjustment","newBalance","transactionId"]}},"required":["success","data"]},"AdjustmentRequest":{"type":"object","properties":{"amount":{"type":"number","example":-5000,"description":"Positive or negative iC"},"description":{"type":"string","example":"Refund for service outage","description":"Reason for adjustment"}},"required":["amount","description"]},"SystemHealth":{"type":"object","properties":{"status":{"type":"string","enum":["healthy","degraded","unhealthy"]},"version":{"type":"string"},"checkedAt":{"type":"string"},"components":{"type":"object","properties":{"upstash":{"type":"object","properties":{"ok":{"type":"boolean"},"latencyMs":{"type":["number","null"]},"error":{"type":["string","null"],"enum":["timeout","unavailable","not_configured"]},"count":{"type":"number"}},"required":["ok","latencyMs","error"]},"d1":{"type":"object","properties":{"ok":{"type":"boolean"},"latencyMs":{"type":["number","null"]},"error":{"type":["string","null"],"enum":["timeout","unavailable","not_configured"]},"count":{"type":"number"}},"required":["ok","latencyMs","error"]},"kvApiKeys":{"type":"object","properties":{"ok":{"type":"boolean"},"latencyMs":{"type":["number","null"]},"error":{"type":["string","null"],"enum":["timeout","unavailable","not_configured"]},"count":{"type":"number"}},"required":["ok","latencyMs","error"]},"r2Providers":{"type":"object","properties":{"ok":{"type":"boolean"},"latencyMs":{"type":["number","null"]},"error":{"type":["string","null"],"enum":["timeout","unavailable","not_configured"]},"count":{"type":"number"}},"required":["ok","latencyMs","error"]},"r2EngineLogs":{"type":"object","properties":{"ok":{"type":"boolean"},"latencyMs":{"type":["number","null"]},"error":{"type":["string","null"],"enum":["timeout","unavailable","not_configured"]},"count":{"type":"number"}},"required":["ok","latencyMs","error"]},"vectorize":{"type":"object","properties":{"ok":{"type":"boolean"},"latencyMs":{"type":["number","null"]},"error":{"type":["string","null"],"enum":["timeout","unavailable","not_configured"]},"count":{"type":"number"}},"required":["ok","latencyMs","error"]},"circuitBreakerDO":{"type":"object","properties":{"ok":{"type":"boolean"},"latencyMs":{"type":["number","null"]},"error":{"type":["string","null"],"enum":["timeout","unavailable","not_configured"]},"count":{"type":"number"}},"required":["ok","latencyMs","error"]},"rateLimiterDO":{"type":"object","properties":{"ok":{"type":"boolean"},"latencyMs":{"type":["number","null"]},"error":{"type":["string","null"],"enum":["timeout","unavailable","not_configured"]},"count":{"type":"number"}},"required":["ok","latencyMs","error"]}},"required":["upstash","d1","kvApiKeys","r2Providers","r2EngineLogs","vectorize","circuitBreakerDO","rateLimiterDO"]},"crons":{"type":["object","null"],"additionalProperties":{"type":"object","properties":{"lastRunAt":{"type":["string","null"]},"lastOutcome":{"type":["string","null"],"enum":["ok","error"]},"lastDurationMs":{"type":["number","null"]},"lastError":{"type":["string","null"]}},"required":["lastRunAt","lastOutcome","lastDurationMs","lastError"]}},"upstashUsage":{"type":["object","null"],"properties":{"keys":{"type":["number","null"]},"usedMemoryBytes":{"type":["number","null"]}},"required":["keys","usedMemoryBytes"]}},"required":["status","version","checkedAt","components","crons","upstashUsage"]},"UserBalanceResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"available":{"type":"number","example":95000,"description":"Available iC"},"reserved":{"type":"number","example":500,"description":"Reserved iC"},"nextExpiration":{"type":["string","null"],"example":"2026-07-22T00:00:00Z","description":"Next package expiration date"},"alerts":{"type":"object","properties":{"threshold50":{"type":"boolean","example":false},"threshold80":{"type":"boolean","example":false},"threshold90":{"type":"boolean","example":false},"threshold100":{"type":"boolean","example":false}},"required":["threshold50","threshold80","threshold90","threshold100"]}},"required":["available","reserved","nextExpiration","alerts"]}},"required":["success","data"]},"UserTransactionsResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"transactions":{"type":"array","items":{"$ref":"#/components/schemas/Transaction"}},"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"},"hasMore":{"type":"boolean"}},"required":["transactions","total","limit","offset","hasMore"]}},"required":["success","data"]}},"parameters":{}},"paths":{"/health":{"get":{"tags":["System"],"summary":"Health check","description":"Check API health status and component availability. No authentication required.\n\n**LLM USAGE:** Call this to verify the API is operational before making requests.\n\n**RESPONSE:**\n- status: \"healthy\", \"degraded\", or \"unhealthy\"\n- version: Current API version\n- components: Status of catalog, vectorize, cache, database","operationId":"getHealth","security":[],"responses":{"200":{"description":"Server is healthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/execute":{"post":{"tags":["Query"],"summary":"Execute data query","description":"Execute a data query. The engine picks the source for each call and falls back automatically when one fails.\n\n**LLM INTEGRATION GUIDE:**\n\n1. **PREREQUISITES - ALWAYS do this first:**\n   - Call GET /catalog/search?q=your_query to find the right service using natural language\n   - Or call GET /catalog to browse all available services\n   - Check GET /account/balance to verify you have sufficient credits\n\n2. **SERVICE FORMAT:**\n   - The \"service\" field uses format: \"service:endpoint\" (e.g., \"cpf:basic\", \"cnpj:complete\")\n   - Available services include: cpf, cnpj, cep, processo, and more\n   - Use /catalog to discover all options - DO NOT guess service names\n\n3. **DOCUMENT FORMAT:**\n   - The \"document\" field is the query input (CPF number, CNPJ number, CEP, etc.)\n   - Format depends on service: CPF = 11 digits, CNPJ = 14 digits, CEP = 8 digits\n   - Check /catalog/adh/{service:endpoint} for exact format requirements\n\n**EXAMPLE WORKFLOW:**\n1. User asks \"validate CPF 12345678900\"\n2. Call: GET /catalog/search?q=validate%20cpf → finds \"cpf:basic\"\n3. Call: POST /execute with {\"service\": \"cpf:basic\", \"document\": \"12345678900\"}\n\n**COMMON ERRORS:**\n- 402 (INSUFFICIENT_CREDITS): User needs to add credits via admin\n- 404 (SERVICE_NOT_FOUND): Invalid service - check /catalog for valid options\n- 400 (VALIDATION_ERROR): Document format invalid for service type","operationId":"execute","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EngineRequest"}}}},"responses":{"200":{"description":"Query executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EngineResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EngineResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EngineResponse"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EngineResponse"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EngineResponse"}}}},"404":{"description":"Service or data not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EngineResponse"}}}},"409":{"description":"Conflict with the current state of the resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EngineResponse"}}}},"413":{"description":"Payload too large for the provider","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EngineResponse"}}}},"422":{"description":"Request understood but semantically refused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EngineResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EngineResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EngineResponse"}}}},"502":{"description":"Upstream provider failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EngineResponse"}}}}}}},"/catalog":{"get":{"tags":["Catalog"],"summary":"List all providers","description":"List the providers in the ADH Engine catalog.\n\n**LLM USAGE:** Call this FIRST to discover what services are available before calling /execute.\n\n**RESPONSE STRUCTURE:**\n- providers[]: List of provider objects with name, description, serviceCount\n- Customer keys see one provider, `adh` (APIDevHub), that groups every service; the engine picks the source behind each call\n\n**NEXT STEPS:**\n- To see services for a provider: GET /catalog/{provider}\n- To search by natural language: GET /catalog/search?q=your_query\n- To execute a query: POST /execute (after finding the right service)","operationId":"listProviders","responses":{"200":{"description":"List of providers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogProvidersResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogErrorResponse"}}}}}}},"/catalog/search":{"get":{"tags":["Catalog"],"summary":"Search endpoints","description":"Search for services using natural language (semantic search powered by AI).\n\n**LLM USAGE:** This is the RECOMMENDED way to find services. Accepts natural language queries.\n\n**QUERY EXAMPLES:**\n- \"validate brazilian CPF\" → finds cpf:basic\n- \"company information by CNPJ\" → finds cnpj:complete\n- \"address lookup by zip code\" → finds cep:v2\n- \"consultar sócios de uma empresa\" → finds the cnpj QSA endpoints\n\nQueries work in Portuguese and English. Results below a relevance floor are\nomitted: an empty `results` list means nothing in the catalog matches.\n\n**PARAMETERS:**\n- q (required): Natural language search query\n- limit (optional): Max results (default 10)\n- provider (optional): Filter by provider (operator keys only)\n- service (optional): Filter by service type\n\n**WORKFLOW:**\n1. Call this endpoint with user's intent\n2. Get matching service from results\n3. Use that service in POST /execute","operationId":"searchEndpoints","parameters":[{"schema":{"type":"string","minLength":1,"example":"validar cpf cliente","description":"Search query"},"required":true,"description":"Search query","name":"q","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":50,"default":10,"example":10,"description":"Max results (1-50)"},"required":false,"description":"Max results (1-50)","name":"limit","in":"query"},{"schema":{"type":"string","description":"Filter by provider (operator keys only; ignored for customer keys)"},"required":false,"description":"Filter by provider (operator keys only; ignored for customer keys)","name":"provider","in":"query"},{"schema":{"type":"string","example":"cpf","description":"Filter by service"},"required":false,"description":"Filter by service","name":"service","in":"query"}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogSearchResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogErrorResponse"}}}}}}},"/catalog/{provider}":{"get":{"tags":["Catalog"],"summary":"List services for a provider","description":"List all services and endpoints available from a specific provider (`adh` for customer keys).\n\n**LLM USAGE:** Use GET /catalog/adh to list every service you can call.\n\n**RESPONSE:** Returns services array with endpoints, each containing:\n- service: Service identifier (e.g., \"cpf\", \"cnpj\")\n- endpoints: Available endpoints (e.g., \"basic\", \"complete\")\n- To use: combine as \"service:endpoint\" in /execute","operationId":"getProviderServices","parameters":[{"schema":{"type":"string","minLength":1,"example":"adh","description":"Provider code (`adh` for customer keys)"},"required":true,"description":"Provider code (`adh` for customer keys)","name":"provider","in":"path"}],"responses":{"200":{"description":"Provider services","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogProviderServicesResponse"}}}},"404":{"description":"Provider not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogErrorResponse"}}}}}}},"/catalog/{provider}/{serviceEndpoint}":{"get":{"tags":["Catalog"],"summary":"Get endpoint details","description":"Get complete details for a specific endpoint including pricing, document format, and fields returned.\n\n**LLM USAGE:** Call this to understand exact requirements before calling /execute.\n\n**IMPORTANT FIELDS:**\n- document.type: Required input type (CPF, CNPJ, CEP, etc.)\n- document.format: Input format/regex\n- pricing.iC: Information cost per request\n- pricing.pC: Processing cost per request\n- response.fields: What data is returned","operationId":"getEndpointDetails","parameters":[{"schema":{"type":"string","minLength":1,"example":"adh","description":"Provider code (`adh` for customer keys)"},"required":true,"description":"Provider code (`adh` for customer keys)","name":"provider","in":"path"},{"schema":{"type":"string","minLength":1,"example":"cpf:basic","description":"Service and endpoint in format service:endpoint"},"required":true,"description":"Service and endpoint in format service:endpoint","name":"serviceEndpoint","in":"path"}],"responses":{"200":{"description":"Endpoint details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogEndpointResponse"}}}},"404":{"description":"Endpoint not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogErrorResponse"}}}}}}},"/catalog-admin/index":{"post":{"tags":["Catalog Admin"],"summary":"Index catalog in Vectorize","description":"Generates embeddings and indexes all catalog entries in Vectorize for semantic search.","operationId":"indexCatalog","responses":{"200":{"description":"Indexing completed","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"indexed":{"type":"number"},"duration":{"type":"number"}},"required":["indexed","duration"]}},"required":["success","data"]}}}},"500":{"description":"Indexing failed","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["success","error"]}}}}}}},"/catalog-admin/enrich":{"post":{"tags":["Catalog Admin"],"summary":"Run AI enrichment for catalog entry","description":"Calls Workers AI with provided messages and returns the response text. Used by catalog generator for entry enrichment.","operationId":"enrichCatalogEntry","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"messages":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["system","user","assistant"]},"content":{"type":"string"}},"required":["role","content"]}},"model":{"type":"string","default":"@cf/meta/llama-3.3-70b-instruct-fp8-fast"},"max_tokens":{"type":"number","default":2048}},"required":["messages"]}}}},"responses":{"200":{"description":"AI enrichment completed","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"response":{"type":"string"}},"required":["response"]}},"required":["success","data"]}}}},"500":{"description":"AI enrichment failed","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["success","error"]}}}}}}},"/cache/all":{"get":{"tags":["Cache"],"summary":"Get validation code for clear all","description":"Generates a single-use validation code required to clear all cache. Code expires in 60 seconds.","operationId":"getCacheValidationCode","responses":{"200":{"description":"Validation code generated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationCodeResponse"}}}},"403":{"description":"Access denied - HQ role required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CacheDeleteError"}}}}}},"post":{"tags":["Cache"],"summary":"Clear all cache","description":"Clears all data cache. Requires validation code from GET /cache/all.","operationId":"clearAllCache","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClearAllRequest"}}}},"responses":{"200":{"description":"Cache cleared","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CacheDeleteResponse"}}}},"400":{"description":"Invalid or expired validation code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CacheDeleteError"}}}},"403":{"description":"Access denied - HQ role required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CacheDeleteError"}}}}}}},"/cache/{provider}":{"delete":{"tags":["Cache"],"summary":"Delete cache by provider","description":"Deletes all cache entries for a specific provider.","operationId":"deleteCacheByProvider","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]+$","example":"provider-a"},"required":true,"name":"provider","in":"path"}],"responses":{"200":{"description":"Cache deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CacheDeleteResponse"}}}},"400":{"description":"Cache not available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CacheDeleteError"}}}},"403":{"description":"Access denied - Admin role required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CacheDeleteError"}}}}}}},"/cache/{provider}/{service}":{"delete":{"tags":["Cache"],"summary":"Delete cache by service","description":"Deletes all cache entries for a specific provider and service.","operationId":"deleteCacheByService","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]+$","example":"provider-a"},"required":true,"name":"provider","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]+$","example":"cpf"},"required":true,"name":"service","in":"path"}],"responses":{"200":{"description":"Cache deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CacheDeleteResponse"}}}},"400":{"description":"Cache not available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CacheDeleteError"}}}},"403":{"description":"Access denied - Admin role required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CacheDeleteError"}}}}}}},"/cache/{provider}/{service}/{endpoint}":{"delete":{"tags":["Cache"],"summary":"Delete cache by endpoint","description":"Deletes all cache entries for a specific provider, service, and endpoint.","operationId":"deleteCacheByEndpoint","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]+$","example":"provider-a"},"required":true,"name":"provider","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]+$","example":"cpf"},"required":true,"name":"service","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]+$","example":"basic"},"required":true,"name":"endpoint","in":"path"}],"responses":{"200":{"description":"Cache deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CacheDeleteResponse"}}}},"400":{"description":"Cache not available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CacheDeleteError"}}}},"403":{"description":"Access denied - Admin role required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CacheDeleteError"}}}}}}},"/cache/{provider}/{service}/{endpoint}/{document}":{"delete":{"tags":["Cache"],"summary":"Delete cache by document","description":"Deletes cache entry for a specific document.","operationId":"deleteCacheByDocument","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]+$","example":"provider-a"},"required":true,"name":"provider","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]+$","example":"cpf"},"required":true,"name":"service","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]+$","example":"basic"},"required":true,"name":"endpoint","in":"path"},{"schema":{"type":"string","example":"12345678900"},"required":true,"name":"document","in":"path"}],"responses":{"200":{"description":"Cache deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CacheDeleteResponse"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CacheDeleteError"}}}}}}},"/cache/config/all":{"post":{"tags":["Cache"],"summary":"Invalidate all config cache","description":"Invalidates all configuration caches (providers, services, endpoints).","operationId":"invalidateAllConfigCache","responses":{"200":{"description":"Config cache invalidated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigInvalidateResponse"}}}},"403":{"description":"Access denied - HQ role required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CacheDeleteError"}}}}}}},"/cache/config/{target}":{"post":{"tags":["Cache"],"summary":"Invalidate config cache by target","description":"Invalidates configuration cache for a specific provider or service.","operationId":"invalidateConfigCacheByTarget","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]+$","example":"provider-a"},"required":true,"name":"target","in":"path"}],"responses":{"200":{"description":"Config cache invalidated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigInvalidateResponse"}}}},"403":{"description":"Access denied - Admin role required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CacheDeleteError"}}}}}}},"/cache/circuit-breaker/{provider}/reset":{"post":{"tags":["Cache"],"summary":"Reset circuit breaker for a provider","description":"Resets the circuit breaker state for a specific provider to closed.","operationId":"resetCircuitBreaker","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]+$","example":"provider-a"},"required":true,"name":"provider","in":"path"}],"responses":{"200":{"description":"Circuit breaker reset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigInvalidateResponse"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CacheDeleteError"}}}}}}},"/adh-hq/users":{"post":{"tags":["HQ - Users"],"summary":"Create user","description":"Creates a new user in the system","operationId":"createUser","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUser"}}}},"responses":{"201":{"description":"User created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserCreatedResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserError"}}}},"409":{"description":"Email already registered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DuplicateEmailError"}}}}}},"get":{"tags":["HQ - Users"],"summary":"List users","description":"Lists users with optional filtering and pagination","operationId":"listUsers","parameters":[{"schema":{"type":"string","example":"user@"},"required":false,"name":"email","in":"query"},{"schema":{"type":"string","example":"John"},"required":false,"name":"name","in":"query"},{"schema":{"type":"string","example":"ACME"},"required":false,"name":"company","in":"query"},{"schema":{"type":"string","example":true},"required":false,"name":"active","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":50,"example":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":["number","null"],"minimum":0,"default":0,"example":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"Users list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserListResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserError"}}}}}}},"/adh-hq/users/{id}":{"get":{"tags":["HQ - Users"],"summary":"Get user by ID","description":"Retrieves a single user by their ID","operationId":"getUser","parameters":[{"schema":{"type":"string","example":"01912345-6789-7abc-def0-123456789abc","description":"User ID (UUIDv7)"},"required":true,"description":"User ID (UUIDv7)","name":"id","in":"path"}],"responses":{"200":{"description":"User found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserResponse"}}}},"404":{"description":"User not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserError"}}}}}},"patch":{"tags":["HQ - Users"],"summary":"Update user","description":"Updates an existing user","operationId":"updateUser","parameters":[{"schema":{"type":"string","example":"01912345-6789-7abc-def0-123456789abc","description":"User ID (UUIDv7)"},"required":true,"description":"User ID (UUIDv7)","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateUser"}}}},"responses":{"200":{"description":"User updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserError"}}}},"404":{"description":"User not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserError"}}}}}},"delete":{"tags":["HQ - Users"],"summary":"Deactivate user","description":"Deactivates a user (soft delete)","operationId":"deleteUser","parameters":[{"schema":{"type":"string","example":"01912345-6789-7abc-def0-123456789abc","description":"User ID (UUIDv7)"},"required":true,"description":"User ID (UUIDv7)","name":"id","in":"path"}],"responses":{"200":{"description":"User deactivated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserDeletedResponse"}}}},"404":{"description":"User not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserError"}}}}}}},"/adh-hq/keys":{"post":{"tags":["HQ - API Keys"],"summary":"Create API key","description":"Creates a new API key for a user. The full key is only shown once.","operationId":"createApiKey","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiKey"}}}},"responses":{"201":{"description":"API key created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyCreatedResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyError"}}}},"404":{"description":"User not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserNotFoundError"}}}},"409":{"description":"User is inactive (USER_INACTIVE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyError"}}}}}},"get":{"tags":["HQ - API Keys"],"summary":"List API keys","description":"Lists API keys with optional filtering and pagination","operationId":"listApiKeys","parameters":[{"schema":{"type":"string","example":"01912345-6789-7abc-def0-123456789abc"},"required":false,"name":"user_id","in":"query"},{"schema":{"$ref":"#/components/schemas/ApiKeyRole"},"required":false,"name":"role","in":"query"},{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiKeyPlan"},{"example":"pro"}]},"required":false,"name":"plan","in":"query"},{"schema":{"type":"string","example":true},"required":false,"name":"active","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":50,"example":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":["number","null"],"minimum":0,"default":0,"example":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"API keys list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyListResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyError"}}}}}}},"/adh-hq/keys/{id}":{"get":{"tags":["HQ - API Keys"],"summary":"Get API key by ID","description":"Retrieves a single API key by its ID (key value is not shown)","operationId":"getApiKey","parameters":[{"schema":{"type":"string","example":"01912345-6789-7abc-def0-123456789abc","description":"API Key ID (UUIDv7)"},"required":true,"description":"API Key ID (UUIDv7)","name":"id","in":"path"}],"responses":{"200":{"description":"API key found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyResponse"}}}},"404":{"description":"API key not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyError"}}}}}},"patch":{"tags":["HQ - API Keys"],"summary":"Update API key","description":"Updates an existing API key settings","operationId":"updateApiKey","parameters":[{"schema":{"type":"string","example":"01912345-6789-7abc-def0-123456789abc","description":"API Key ID (UUIDv7)"},"required":true,"description":"API Key ID (UUIDv7)","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateApiKey"}}}},"responses":{"200":{"description":"API key updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyError"}}}},"404":{"description":"API key not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyError"}}}},"409":{"description":"Revoked keys cannot be reactivated (KEY_REVOKED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyError"}}}}}},"delete":{"tags":["HQ - API Keys"],"summary":"Revoke API key","description":"Revokes an API key (soft delete)","operationId":"revokeApiKey","parameters":[{"schema":{"type":"string","example":"01912345-6789-7abc-def0-123456789abc","description":"API Key ID (UUIDv7)"},"required":true,"description":"API Key ID (UUIDv7)","name":"id","in":"path"}],"responses":{"200":{"description":"API key revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyDeletedResponse"}}}},"404":{"description":"API key not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyError"}}}}}}},"/adh-hq/keys/{id}/rotate":{"post":{"tags":["HQ - API Keys"],"summary":"Rotate API key","description":"Generates a new key value for an existing API key. The new key is created first, then the old one is revoked.","operationId":"rotateApiKey","parameters":[{"schema":{"type":"string","example":"01912345-6789-7abc-def0-123456789abc","description":"API Key ID (UUIDv7)"},"required":true,"description":"API Key ID (UUIDv7)","name":"id","in":"path"}],"responses":{"200":{"description":"API key rotated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyRotatedResponse"}}}},"404":{"description":"API key not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyError"}}}},"409":{"description":"Key is revoked (KEY_REVOKED) or its user is inactive (USER_INACTIVE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyError"}}}}}}},"/adh-hq/history":{"get":{"tags":["HQ - History"],"summary":"List request history","description":"Lists request history with optional filtering and pagination","operationId":"listHistory","parameters":[{"schema":{"type":"string","example":"sha256..."},"required":false,"name":"api_key_hash","in":"query"},{"schema":{"type":"string","example":"01912345-6789-7abc-def0-123456789abc"},"required":false,"name":"user_id","in":"query"},{"schema":{"type":"string","example":"cpf"},"required":false,"name":"service","in":"query"},{"schema":{"type":"string","example":"basic"},"required":false,"name":"endpoint","in":"query"},{"schema":{"type":"string","example":"provider-a"},"required":false,"name":"provider_code","in":"query"},{"schema":{"type":"string","example":true},"required":false,"name":"success","in":"query"},{"schema":{"type":["number","null"],"example":1705323000000},"required":false,"name":"start_date","in":"query"},{"schema":{"type":["number","null"],"example":1705409400000},"required":false,"name":"end_date","in":"query"},{"schema":{"type":"string","default":false,"example":false},"required":false,"name":"include_deleted","in":"query"},{"schema":{"type":"string","enum":["requestTimestamp","latencyMs","statusCode","informationCost","processingCost"],"default":"requestTimestamp","example":"latencyMs","description":"Column to order by, across every page (server side). Ties fall back to requestTimestamp DESC, then id, so over the same set of rows limit/offset pages neither repeat nor skip one (a request recorded between two page loads shifts the offset, as with the default order)."},"required":false,"description":"Column to order by, across every page (server side). Ties fall back to requestTimestamp DESC, then id, so over the same set of rows limit/offset pages neither repeat nor skip one (a request recorded between two page loads shifts the offset, as with the default order).","name":"sort","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc","example":"desc","description":"Sort direction"},"required":false,"description":"Sort direction","name":"order","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":1000,"default":100,"example":100},"required":false,"name":"limit","in":"query"},{"schema":{"type":["number","null"],"minimum":0,"default":0,"example":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"Request history list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestHistoryListResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HistoryError"}}}}}}},"/adh-hq/history/{requestId}/payload":{"get":{"tags":["HQ - History"],"summary":"Get request payload","description":"Retrieves the full request/response payload stored in R2","operationId":"getPayload","parameters":[{"schema":{"type":"string","example":"req_abc123","description":"Request ID"},"required":true,"description":"Request ID","name":"requestId","in":"path"}],"responses":{"200":{"description":"Payload found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayloadResponse"}}}},"404":{"description":"Payload not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HistoryError"}}}},"500":{"description":"R2 storage not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/R2NotConfiguredError"}}}}}}},"/adh-hq/history/backfill":{"post":{"tags":["HQ - History"],"summary":"Backfill history fields from payloads","description":"Updates records with service=unknown by reading correct values from R2 payloads","operationId":"backfillHistory","parameters":[{"schema":{"type":"number","minimum":1,"maximum":100,"default":50,"example":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","default":false,"example":false},"required":false,"name":"dry_run","in":"query"},{"schema":{"type":"string","enum":["service","provider"],"default":"service","example":"service"},"required":false,"name":"field","in":"query"}],"responses":{"200":{"description":"Backfill completed","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"processed":{"type":"number"},"updated":{"type":"number"},"skipped":{"type":"number"},"errors":{"type":"number"},"remaining":{"type":"number"},"dryRun":{"type":"boolean"}},"required":["processed","updated","skipped","errors","remaining","dryRun"]}},"required":["success","data"]}}}},"500":{"description":"R2 storage not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/R2NotConfiguredError"}}}}}}},"/adh-hq/history/recover":{"post":{"tags":["HQ - History"],"summary":"Recover missing request history from R2 payloads","description":"Reconstructs request_history records from payloads stored in R2, with cursor pagination","operationId":"recoverHistory","parameters":[{"schema":{"type":"number","minimum":1,"maximum":200,"default":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","default":false},"required":false,"name":"dry_run","in":"query"}],"responses":{"200":{"description":"Recovery batch completed","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"processed":{"type":"number"},"inserted":{"type":"number"},"skipped":{"type":"number"},"errors":{"type":"number"},"errorDetails":{"type":"array","items":{"type":"string"}},"cursor":{"type":["string","null"]},"hasMore":{"type":"boolean"}},"required":["processed","inserted","skipped","errors","cursor","hasMore"]}},"required":["success","data"]}}}},"500":{"description":"R2 storage not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/R2NotConfiguredError"}}}}}}},"/adh-hq/billing":{"get":{"tags":["HQ - Billing"],"summary":"Get billing data","description":"Retrieves aggregated cost data grouped by day or month","operationId":"getBilling","parameters":[{"schema":{"type":"string","example":"sha256...","description":"API key hash (required)"},"required":true,"description":"API key hash (required)","name":"api_key_hash","in":"query"},{"schema":{"type":["number","null"],"example":1705323000000,"description":"Start date (Unix timestamp ms)"},"required":false,"description":"Start date (Unix timestamp ms)","name":"start_date","in":"query"},{"schema":{"type":["number","null"],"example":1705409400000,"description":"End date (Unix timestamp ms)"},"required":false,"description":"End date (Unix timestamp ms)","name":"end_date","in":"query"},{"schema":{"type":"string","enum":["day","month"],"default":"day","example":"day"},"required":false,"name":"group_by","in":"query"}],"responses":{"200":{"description":"Billing data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingError"}}}}}}},"/adh-hq/billing/usage":{"get":{"tags":["HQ - Billing"],"summary":"Get service usage","description":"Retrieves usage statistics grouped by service and endpoint","operationId":"getUsage","parameters":[{"schema":{"type":"string","example":"sha256...","description":"API key hash (required)"},"required":true,"description":"API key hash (required)","name":"api_key_hash","in":"query"},{"schema":{"type":["number","null"],"example":1705323000000,"description":"Start date (Unix timestamp ms)"},"required":false,"description":"Start date (Unix timestamp ms)","name":"start_date","in":"query"},{"schema":{"type":["number","null"],"example":1705409400000,"description":"End date (Unix timestamp ms)"},"required":false,"description":"End date (Unix timestamp ms)","name":"end_date","in":"query"}],"responses":{"200":{"description":"Usage data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingError"}}}}}}},"/adh-hq/billing/summary":{"get":{"tags":["HQ - Billing"],"summary":"Get billing summary with credits","description":"Retrieves billing summary including credit balance and period usage","operationId":"getBillingSummary","parameters":[{"schema":{"type":"string","example":"user_123","description":"User ID (required)"},"required":true,"description":"User ID (required)","name":"user_id","in":"query"},{"schema":{"type":["number","null"],"example":1705323000000,"description":"Start date (Unix timestamp ms)"},"required":false,"description":"Start date (Unix timestamp ms)","name":"start_date","in":"query"},{"schema":{"type":["number","null"],"example":1705409400000,"description":"End date (Unix timestamp ms)"},"required":false,"description":"End date (Unix timestamp ms)","name":"end_date","in":"query"}],"responses":{"200":{"description":"Billing summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingSummaryResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingError"}}}}}}},"/adh-hq/credits/{userId}":{"post":{"tags":["HQ - Credits"],"summary":"Add credits to user","description":"Adds a credit package to a user's account with optional expiration date","operationId":"addCredits","parameters":[{"schema":{"type":"string","example":"user_123","description":"User ID"},"required":true,"description":"User ID","name":"userId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddCreditsRequest"}}}},"responses":{"201":{"description":"Credits added successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddCreditsResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditsError"}}}},"404":{"description":"User not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditsError"}}}}}}},"/adh-hq/credits/{userId}/balance":{"get":{"tags":["HQ - Credits"],"summary":"Get user balance","description":"Retrieves the current credit balance for a user","operationId":"getUserBalance","parameters":[{"schema":{"type":"string","example":"user_123","description":"User ID"},"required":true,"description":"User ID","name":"userId","in":"path"}],"responses":{"200":{"description":"Balance retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BalanceResponse"}}}},"404":{"description":"User not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditsError"}}}}}}},"/adh-hq/credits/{userId}/packages":{"get":{"tags":["HQ - Credits"],"summary":"List user packages","description":"Lists all active credit packages for a user","operationId":"getUserPackages","parameters":[{"schema":{"type":"string","example":"user_123","description":"User ID"},"required":true,"description":"User ID","name":"userId","in":"path"}],"responses":{"200":{"description":"Packages list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PackagesResponse"}}}},"404":{"description":"User not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditsError"}}}}}}},"/adh-hq/credits/{userId}/transactions":{"get":{"tags":["HQ - Credits"],"summary":"List user transactions","description":"Lists credit transactions for a user with optional filtering","operationId":"getUserTransactions","parameters":[{"schema":{"type":"string","example":"user_123","description":"User ID"},"required":true,"description":"User ID","name":"userId","in":"path"},{"schema":{"type":"string","enum":["credit","debit","reserve","confirm","release","expire","adjustment","alert"],"example":"credit"},"required":false,"name":"type","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Filter from date"},"required":false,"description":"Filter from date","name":"start_date","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Filter to date"},"required":false,"description":"Filter to date","name":"end_date","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":50,"example":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":["number","null"],"minimum":0,"default":0,"example":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"Transactions list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionsResponse"}}}},"404":{"description":"User not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditsError"}}}}}}},"/adh-hq/credits/{userId}/adjustment":{"post":{"tags":["HQ - Credits"],"summary":"Manual balance adjustment","description":"Manually adjusts a user's credit balance (positive or negative)","operationId":"adjustBalance","parameters":[{"schema":{"type":"string","example":"user_123","description":"User ID"},"required":true,"description":"User ID","name":"userId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdjustmentRequest"}}}},"responses":{"200":{"description":"Adjustment applied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdjustmentResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditsError"}}}},"404":{"description":"User not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditsError"}}}}}}},"/adh-hq/system/health":{"get":{"tags":["HQ - System"],"summary":"Infrastructure health (hq only)","description":"Latency of each binding (Upstash PING, D1 SELECT 1, KV get, R2 head, Vectorize describe, Durable Object status), each with its own 2 s timeout; the last run of each cron; Upstash key count and memory. Errors carry a generic code only. The public /health is unchanged.","operationId":"getSystemHealth","responses":{"200":{"description":"Infrastructure health","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SystemHealth"}}}}}}},"/account/balance":{"get":{"tags":["Account"],"summary":"Get your credit balance","description":"Get your current credit balance and alert status.\n\n**LLM USAGE:** Check this BEFORE calling /execute to ensure sufficient credits.\n\n**RESPONSE FIELDS:**\n- available: Credits available for use\n- reserved: Credits reserved for pending requests\n- nextExpiration: When credits will expire (ISO date)\n- alerts: Threshold alerts (50%, 80%, 90%, 100% consumed)\n\n**IMPORTANT:** If available is 0, /execute will return 402 error.","operationId":"getAccountBalance","security":[{"apiKey":[]}],"responses":{"200":{"description":"Current balance information","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserBalanceResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditsError"}}}}}}},"/account/transactions":{"get":{"tags":["Account"],"summary":"Get your transaction history","description":"Returns your credit transaction history with pagination and filtering.","operationId":"getAccountTransactions","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["credit","debit","reserve","confirm","release","expire","adjustment","alert"],"example":"credit"},"required":false,"name":"type","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Filter from date"},"required":false,"description":"Filter from date","name":"start_date","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Filter to date"},"required":false,"description":"Filter to date","name":"end_date","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":50,"example":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":["number","null"],"minimum":0,"default":0,"example":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"Transaction history","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserTransactionsResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditsError"}}}}}}},"/openapi.json":{"get":{"tags":["OpenAPI"],"summary":"Get OpenAPI specification","description":"Get the OpenAPI 3.1 specification. Use query params to filter:\n- path: Filter by path prefix (e.g., ?path=/execute)\n- tag: Filter by tag (e.g., ?tag=Catalog)\nWithout parameters, returns complete spec.","parameters":[{"schema":{"type":"string","example":"/execute","description":"Filter by path prefix (e.g., /execute, /catalog)"},"required":false,"description":"Filter by path prefix (e.g., /execute, /catalog)","name":"path","in":"query"},{"schema":{"type":"string","example":"Execute","description":"Filter by tag name (e.g., Execute, Catalog, Health)"},"required":false,"description":"Filter by tag name (e.g., Execute, Catalog, Health)","name":"tag","in":"query"}],"responses":{"200":{"description":"OpenAPI specification","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}}}}}},"webhooks":{}}