{"openapi":"3.1.0","info":{"title":"Humetric Platform API","description":"Entity metric tracking and signal processing REST API","version":"1.0.0"},"paths":{"/healthz":{"get":{"tags":["Health"],"summary":"Healthz","operationId":"healthz_healthz_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/healthz/db":{"get":{"tags":["Health"],"summary":"Healthz Db","operationId":"healthz_db_healthz_db_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/healthz/worker":{"get":{"tags":["Health"],"summary":"Healthz Worker","operationId":"healthz_worker_healthz_worker_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/entities":{"post":{"tags":["Entities"],"summary":"Create Entity","operationId":"create_entity_v1_entities_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"200":{"description":"Existing entity updated"},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"tags":["Entities"],"summary":"List Entities","operationId":"list_entities_v1_entities_get","parameters":[{"name":"entity_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Type"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/entities/{entity_id}":{"get":{"tags":["Entities"],"summary":"Get Entity","operationId":"get_entity_v1_entities__entity_id__get","parameters":[{"name":"entity_id","in":"path","required":true,"schema":{"type":"string","title":"Entity Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/entities/{entity_id}/metrics":{"get":{"tags":["Entities"],"summary":"Get Entity Metrics Endpoint","operationId":"get_entity_metrics_endpoint_v1_entities__entity_id__metrics_get","parameters":[{"name":"entity_id","in":"path","required":true,"schema":{"type":"string","title":"Entity Id"}},{"name":"include_history","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include History"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/entities/{entity_id}/metrics/{metric_key}/explain":{"get":{"tags":["Entities"],"summary":"Explain Metric","operationId":"explain_metric_v1_entities__entity_id__metrics__metric_key__explain_get","parameters":[{"name":"entity_id","in":"path","required":true,"schema":{"type":"string","title":"Entity Id"}},{"name":"metric_key","in":"path","required":true,"schema":{"type":"string","title":"Metric Key"}},{"name":"contributions","in":"query","required":false,"schema":{"type":"integer","default":10,"title":"Contributions"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricExplanation"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Entity or metric not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/entities/{entity_id}/metrics/{metric_key}/history":{"get":{"tags":["Entities"],"summary":"Get Metric History","description":"Time series of a metric, oldest first.\n\n``confidence`` is the value recorded at the time — the honest line to plot.\n``effective_confidence`` applies temporal decay as of *now*, i.e. how much\nthat point is still worth today. They are not interchangeable.","operationId":"get_metric_history_v1_entities__entity_id__metrics__metric_key__history_get","parameters":[{"name":"entity_id","in":"path","required":true,"schema":{"type":"string","title":"Entity Id"}},{"name":"metric_key","in":"path","required":true,"schema":{"type":"string","title":"Metric Key"}},{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Since"}},{"name":"until","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Until"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":200,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricHistoryResponse"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Entity or metric not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/entities/{entity_id}/signals":{"get":{"tags":["Signals"],"summary":"List Entity Signals","operationId":"list_entity_signals_v1_entities__entity_id__signals_get","parameters":[{"name":"entity_id","in":"path","required":true,"schema":{"type":"string","title":"Entity Id"}},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignalListResponse"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Entity not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/signals":{"post":{"tags":["Signals"],"summary":"Create Signal","operationId":"create_signal_v1_signals_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignalCreate"}}},"required":true},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/signals/{signal_id}":{"get":{"tags":["Signals"],"summary":"Get Signal","operationId":"get_signal_v1_signals__signal_id__get","parameters":[{"name":"signal_id","in":"path","required":true,"schema":{"type":"string","title":"Signal Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/signals/{signal_id}/trace":{"get":{"tags":["Signals"],"summary":"Get Signal Trace","operationId":"get_signal_trace_v1_signals__signal_id__trace_get","parameters":[{"name":"signal_id","in":"path","required":true,"schema":{"type":"string","title":"Signal Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/api-keys":{"get":{"tags":["API Keys"],"summary":"List Api Keys","operationId":"list_api_keys_v1_api_keys_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["API Keys"],"summary":"Create Api Key","operationId":"create_api_key_v1_api_keys_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyCreate"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/api-keys/{key_id}":{"delete":{"tags":["API Keys"],"summary":"Delete Api Key","operationId":"delete_api_key_v1_api_keys__key_id__delete","parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"integer","title":"Key Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/audit-logs":{"get":{"tags":["Audit"],"summary":"List Audit Logs","operationId":"list_audit_logs_v1_audit_logs_get","parameters":[{"name":"action","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Action"}},{"name":"entity_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/packs":{"post":{"tags":["Packs"],"summary":"Create Pack","operationId":"create_pack_v1_packs_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PackCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["Packs"],"summary":"List Packs","operationId":"list_packs_v1_packs_get","parameters":[{"name":"is_active","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Active"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/packs/{pack_key}":{"get":{"tags":["Packs"],"summary":"Get Pack","operationId":"get_pack_v1_packs__pack_key__get","parameters":[{"name":"pack_key","in":"path","required":true,"schema":{"type":"string","title":"Pack Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"put":{"tags":["Packs"],"summary":"Update Pack","operationId":"update_pack_v1_packs__pack_key__put","parameters":[{"name":"pack_key","in":"path","required":true,"schema":{"type":"string","title":"Pack Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PackCreate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/packs/wizard":{"post":{"tags":["Packs"],"summary":"Create Pack Wizard","operationId":"create_pack_wizard_v1_packs_wizard_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PackWizardRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/consent":{"post":{"tags":["Consent"],"summary":"Create Consent","operationId":"create_consent_v1_consent_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsentCreate"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/consent/{entity_id}":{"get":{"tags":["Consent"],"summary":"Get Consents","operationId":"get_consents_v1_consent__entity_id__get","parameters":[{"name":"entity_id","in":"path","required":true,"schema":{"type":"string","title":"Entity Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["Consent"],"summary":"Delete Consent","operationId":"delete_consent_v1_consent__entity_id__delete","parameters":[{"name":"entity_id","in":"path","required":true,"schema":{"type":"string","title":"Entity Id"}},{"name":"scope","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scope"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/query":{"post":{"tags":["Query"],"summary":"Query Entities","operationId":"query_entities_v1_query_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/tenant/keys":{"get":{"tags":["Tenant"],"summary":"Get Tenant Keys","operationId":"get_tenant_keys_v1_tenant_keys_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"put":{"tags":["Tenant"],"summary":"Upsert Tenant Keys","operationId":"upsert_tenant_keys_v1_tenant_keys_put","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TenantKeysUpdate"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["Tenant"],"summary":"Delete Tenant Keys","operationId":"delete_tenant_keys_v1_tenant_keys_delete","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/register":{"post":{"tags":["Registration"],"summary":"Register","operationId":"register_v1_register_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/verify-email":{"get":{"tags":["Registration"],"summary":"Verify Email","operationId":"verify_email_v1_verify_email_get","parameters":[{"name":"token","in":"query","required":true,"schema":{"type":"string","title":"Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/login":{"post":{"tags":["Registration"],"summary":"Login","operationId":"login_v1_login_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/tenant/dashboard":{"get":{"tags":["Tenant"],"summary":"Tenant Dashboard","operationId":"tenant_dashboard_v1_tenant_dashboard_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/tenant/export":{"post":{"tags":["Tenant"],"summary":"Request Tenant Export","description":"Queue a raw data export (CSV/JSON zip of the tenant's data), emailed on completion.","operationId":"request_tenant_export_v1_tenant_export_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportRequestBody"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/tenant/start-trial":{"post":{"tags":["Tenant"],"summary":"Start Pro Trial","description":"Start the 3-month free Pro trial (once per tenant).","operationId":"start_pro_trial_v1_tenant_start_trial_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/tenant/rotate-api-key":{"post":{"tags":["Tenant"],"summary":"Rotate Api Key","operationId":"rotate_api_key_v1_tenant_rotate_api_key_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/billing/checkout":{"post":{"tags":["Billing"],"summary":"Billing Checkout","operationId":"billing_checkout_v1_billing_checkout_post","parameters":[{"name":"tier","in":"query","required":true,"schema":{"type":"string","title":"Tier"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/billing/webhook":{"post":{"tags":["Billing"],"summary":"Billing Webhook","operationId":"billing_webhook_v1_billing_webhook_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/usage":{"get":{"tags":["Usage"],"summary":"Tenant Usage","operationId":"tenant_usage_v1_usage_get","parameters":[{"name":"start_date","in":"query","required":true,"schema":{"type":"string","title":"Start Date"}},{"name":"end_date","in":"query","required":true,"schema":{"type":"string","title":"End Date"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/usage/calls":{"get":{"tags":["Usage"],"summary":"Tenant Usage Calls","description":"Per-call usage: who called which surface/tool, how often, how fast.\n\nComplements /v1/usage, which reports daily signal/token/embedding volume.\nThis one reports request-level activity — the view that makes MCP usage\nvisible per API key.","operationId":"tenant_usage_calls_v1_usage_calls_get","parameters":[{"name":"start_date","in":"query","required":true,"schema":{"type":"string","title":"Start Date"}},{"name":"end_date","in":"query","required":true,"schema":{"type":"string","title":"End Date"}},{"name":"group_by","in":"query","required":false,"schema":{"type":"string","default":"tool","title":"Group By"}},{"name":"client","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Client"}},{"name":"api_key_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Api Key Id"}},{"name":"tool_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tool Name"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/admin/usage":{"get":{"tags":["Usage"],"summary":"Admin Usage","operationId":"admin_usage_v1_admin_usage_get","parameters":[{"name":"tenant","in":"query","required":true,"schema":{"type":"string","title":"Tenant"}},{"name":"start_date","in":"query","required":true,"schema":{"type":"string","title":"Start Date"}},{"name":"end_date","in":"query","required":true,"schema":{"type":"string","title":"End Date"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/metrics/{entity_id}/{metric_key}/review":{"put":{"tags":["Metrics"],"summary":"Reviewer Override Metric","operationId":"reviewer_override_metric_v1_metrics__entity_id___metric_key__review_put","parameters":[{"name":"entity_id","in":"path","required":true,"schema":{"type":"string","title":"Entity Id"}},{"name":"metric_key","in":"path","required":true,"schema":{"type":"string","title":"Metric Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewerOverrideRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/metrics/pending-review":{"get":{"tags":["Metrics"],"summary":"List Pending Reviews","operationId":"list_pending_reviews_v1_metrics_pending_review_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"ApiKeyCreate":{"properties":{"prefix":{"type":"string","maxLength":16,"pattern":"^(hm_live|hm_test)$","title":"Prefix","default":"hm_test"},"scopes":{"items":{"type":"string"},"type":"array","title":"Scopes"},"label":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Label"},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expires At"},"expires_in_days":{"anyOf":[{"type":"integer","maximum":730.0,"minimum":1.0},{"type":"null"}],"title":"Expires In Days"}},"type":"object","title":"ApiKeyCreate"},"ConsentCreate":{"properties":{"entity_id":{"type":"string","maxLength":128,"title":"Entity Id"},"scope":{"type":"string","maxLength":128,"title":"Scope"},"status":{"$ref":"#/components/schemas/ConsentStatus","default":"granted"},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expires At"}},"type":"object","required":["entity_id","scope"],"title":"ConsentCreate"},"ConsentStatus":{"type":"string","enum":["granted","revoked","expired"],"title":"ConsentStatus"},"EntityCreate":{"properties":{"id":{"type":"string","maxLength":128,"pattern":"^[a-zA-Z0-9\\-_.]+$","title":"Id","description":"Client-provided unique ID"},"entity_type":{"type":"string","maxLength":64,"title":"Entity Type"},"fields":{"additionalProperties":true,"type":"object","title":"Fields"},"free_text":{"anyOf":[{"type":"string","maxLength":50000},{"type":"null"}],"title":"Free Text"},"status":{"type":"string","title":"Status","default":"active"}},"type":"object","required":["id","entity_type"],"title":"EntityCreate"},"ErrorDetail":{"properties":{"code":{"type":"string","title":"Code"},"message":{"type":"string","title":"Message"},"doc_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Doc Url"}},"type":"object","required":["code","message"],"title":"ErrorDetail"},"ErrorResponse":{"properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}},"type":"object","required":["error"],"title":"ErrorResponse"},"ExportRequestBody":{"properties":{"format":{"type":"string","enum":["csv","json"],"title":"Format"}},"type":"object","required":["format"],"title":"ExportRequestBody"},"ExtractedMetric":{"properties":{"metric_key":{"type":"string","title":"Metric Key"},"value":{"type":"number","title":"Value"},"confidence":{"type":"number","title":"Confidence"},"reasoning":{"type":"string","title":"Reasoning","default":""},"needs_review":{"type":"boolean","title":"Needs Review","default":false},"source_span":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Span"}},"type":"object","required":["metric_key","value","confidence"],"title":"ExtractedMetric"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"LoginRequest":{"properties":{"email":{"type":"string","maxLength":255,"title":"Email"},"password":{"type":"string","maxLength":128,"minLength":1,"title":"Password"}},"type":"object","required":["email","password"],"title":"LoginRequest"},"MetricContribution":{"properties":{"recorded_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Recorded At"},"value":{"type":"number","title":"Value"},"prev_value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Prev Value"},"delta":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Delta"},"confidence":{"type":"number","title":"Confidence"},"source_count":{"type":"integer","title":"Source Count","default":1},"signal_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signal Id"},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model"},"reasoning":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reasoning"},"source_span":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Span"}},"type":"object","required":["value","confidence"],"title":"MetricContribution","description":"One historical write of a metric — what moved the score, and why."},"MetricExplanation":{"properties":{"metric_key":{"type":"string","title":"Metric Key"},"value":{"type":"number","title":"Value"},"confidence":{"type":"number","title":"Confidence"},"effective_confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Effective Confidence"},"source_count":{"type":"integer","title":"Source Count","default":1},"last_updated":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Updated"},"source_signal_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Signal Id"},"needs_review":{"type":"boolean","title":"Needs Review","default":false},"extracted":{"items":{"$ref":"#/components/schemas/ExtractedMetric"},"type":"array","title":"Extracted"},"extract_model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Extract Model"},"curator_model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Curator Model"},"contributions":{"items":{"$ref":"#/components/schemas/MetricContribution"},"type":"array","title":"Contributions"},"note":{"type":"string","title":"Note","default":"extracted/extract_model alanları yalnızca en son işlenen sinyale aittir; önceki sinyallerin katkısı için contributions listesine bakın."}},"type":"object","required":["metric_key","value","confidence"],"title":"MetricExplanation"},"MetricHistoryPoint":{"properties":{"recorded_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Recorded At"},"value":{"type":"number","title":"Value"},"prev_value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Prev Value"},"delta":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Delta"},"confidence":{"type":"number","title":"Confidence"},"source_count":{"type":"integer","title":"Source Count","default":1},"signal_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signal Id"},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model"},"reasoning":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reasoning"},"source_span":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Span"},"effective_confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Effective Confidence"}},"type":"object","required":["value","confidence"],"title":"MetricHistoryPoint","description":"A contribution plus today's decayed view of its confidence."},"MetricHistoryResponse":{"properties":{"entity_id":{"type":"string","title":"Entity Id"},"metric_key":{"type":"string","title":"Metric Key"},"points":{"items":{"$ref":"#/components/schemas/MetricHistoryPoint"},"type":"array","title":"Points"},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"}},"type":"object","required":["entity_id","metric_key","total","limit","offset"],"title":"MetricHistoryResponse"},"PackCreate":{"properties":{"yaml_text":{"type":"string","maxLength":102400,"minLength":1,"title":"Yaml Text"},"pack_key":{"type":"string","maxLength":128,"title":"Pack Key","default":""}},"type":"object","required":["yaml_text"],"title":"PackCreate"},"PackWizardRequest":{"properties":{"text":{"type":"string","maxLength":100000,"minLength":10,"title":"Text"},"entity_type_hint":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Entity Type Hint"}},"type":"object","required":["text"],"title":"PackWizardRequest"},"QueryRequest":{"properties":{"entity_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Type"},"rank_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rank By"},"filters":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Filters"},"free_text_query":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Free Text Query"},"top_k":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Top K","default":10},"include_reasoning":{"type":"boolean","title":"Include Reasoning","default":false}},"type":"object","title":"QueryRequest"},"RegisterRequest":{"properties":{"email":{"type":"string","maxLength":255,"title":"Email"},"password":{"type":"string","maxLength":128,"minLength":8,"title":"Password"},"captcha_token":{"type":"string","maxLength":2048,"title":"Captcha Token"}},"type":"object","required":["email","password","captcha_token"],"title":"RegisterRequest"},"ReviewerOverrideRequest":{"properties":{"value":{"type":"number","maximum":1.0,"minimum":-1.0,"title":"Value"},"confidence":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Confidence"},"comment":{"type":"string","title":"Comment","default":""}},"type":"object","required":["value","confidence"],"title":"ReviewerOverrideRequest"},"SignalCreate":{"properties":{"entity_id":{"type":"string","maxLength":128,"title":"Entity Id"},"entity_type":{"type":"string","maxLength":64,"title":"Entity Type"},"text":{"anyOf":[{"type":"string","maxLength":300000},{"type":"null"}],"title":"Text"},"structured":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Structured"},"external_id":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"External Id"},"occurred_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Occurred At"}},"type":"object","required":["entity_id","entity_type"],"title":"SignalCreate"},"SignalListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/SignalSummary"},"type":"array","title":"Items"},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"}},"type":"object","required":["total","limit","offset"],"title":"SignalListResponse"},"SignalSummary":{"properties":{"id":{"type":"string","title":"Id"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Id"},"status":{"type":"string","title":"Status"},"entity_id":{"type":"string","title":"Entity Id"},"pack_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pack Key"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source"},"text_preview":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Text Preview"},"metric_keys":{"items":{"type":"string"},"type":"array","title":"Metric Keys"},"occurred_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Occurred At"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"processed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Processed At"}},"type":"object","required":["id","status","entity_id"],"title":"SignalSummary","description":"List-view row for an entity's signals — no full text, no trace."},"TenantKeysUpdate":{"properties":{"anthropic_key":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Anthropic Key","description":"Plaintext Anthropic API key"},"voyage_key":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Voyage Key","description":"Plaintext Voyage API key"},"openai_key":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Openai Key","description":"Plaintext OpenAI API key"},"google_ai_key":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Google Ai Key","description":"Plaintext Google AI API key"},"deepseek_key":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Deepseek Key","description":"Plaintext DeepSeek API key"},"llm_provider":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Llm Provider","description":"Active LLM provider: anthropic | openai | google | deepseek"}},"type":"object","title":"TenantKeysUpdate"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"HuMetric API key. Create via POST /v1/api-keys"}}},"security":[{"bearerAuth":[]}]}