{"openapi":"3.1.0","info":{"title":"Holdy API","version":"1.0.0","description":"# Behavioral Operating Layer\n\nA Holdy não é analytics. É runtime behavioral semantics layer.\n\nCliente captura **intenção operacional** (workflow.blocked, friction.detected, collaboration.weakened) via 20 primitives canônicos. Backend interpreta + decide interventions + alimenta learning loops.\n\nSpec da taxonomy canônica: 7 categorias × 20 primitives × 4 enums imutáveis. Detalhes em `/docs` (Scalar viewer).","contact":{"name":"Holdy","url":"https://holdy.chat"}},"servers":[{"url":"https://holdy.chat/api/v1","description":"Produção"},{"url":"http://localhost:3000/api/v1","description":"Local dev"}],"tags":[{"name":"Events","description":"Ingest de behavioral primitives canônicos"},{"name":"Memory","description":"Knowledge persistence (notes, observations, CSM context)"},{"name":"Accounts","description":"Upsert COALESCE de account+user vindo do SDK identify()"},{"name":"Behavior","description":"Query agregada do comportamento de uma conta"},{"name":"Risk","description":"Derivação server-side de risk score"},{"name":"Journey","description":"Workflow progression timeline"},{"name":"Taxonomy","description":"Workflows + outcomes declarados pela org"},{"name":"Runtime","description":"Bidirectional decision engine · runtime config + interventions"},{"name":"Capabilities","description":"Discovery · features + rate limits"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key Bearer · gere em /settings → API keys. Formato: `Authorization: Bearer hol_{env}_{prefix}{secret}`. Live = produção · Test = dev local com behavior isolado."}},"schemas":{"IngestEventResponse":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"event_id":{"type":"string","format":"uuid"},"ingested_at":{"type":"string","format":"date-time"},"deduped":{"type":"boolean","description":"true quando o event já existia (mesmo source + external_id + occurred_at)"}},"required":["ok","event_id","ingested_at"]},"IngestErrorResponse":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"code":{"type":"string"},"detail":{"type":"string"}},"required":["type","title","status","code","detail"]},"IngestEventInput":{"type":"object","properties":{"event":{"type":"string","minLength":1,"description":"Nome do evento (bruto, sem canonicalização; ex: workflow.blocked, pageview, invite_sent)","example":"workflow.blocked"},"occurred_at":{"type":"string","format":"date-time","description":"ISO 8601 · quando ocorreu no produto do cliente. Default: now() do servidor.","example":"2026-08-07T18:00:00Z"},"source":{"type":"string","enum":["sdk_web","sdk_server","rest_api","posthog","mixpanel","amplitude","segment","metabase","sql"],"default":"rest_api","description":"Fonte do evento · SDK/adapter identifica. Default: rest_api.","example":"sdk_web"},"user_id":{"type":"string","maxLength":200,"description":"End-user opaco (não Holdy user). Identity resolvida em pipeline downstream."},"anonymous_id":{"type":"string","maxLength":200,"description":"Anonymous ID persistido no cliente (cookie/localStorage)."},"account_id":{"type":"string","format":"uuid","description":"Account (group) UUID. Opcional; resolvida via identity graph se ausente."},"properties":{"type":"object","additionalProperties":{},"default":{},"description":"Props do evento · livre, validado por schema canônico downstream se aplicável."},"context":{"type":"object","additionalProperties":{},"description":"Metadata livre · page, device, feature flags. Não validado."},"external_id":{"type":"string","minLength":1,"maxLength":200,"description":"ID do evento no sistema de origem (uuid PostHog, $insert_id Mixpanel). Dedupe determinístico: re-envio com mesmo (source, external_id, occurred_at) é ignorado."}},"required":["event"]},"BulkIngestResponse":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"accepted":{"type":"integer","minimum":0},"deduped":{"type":"integer","minimum":0},"rejected":{"type":"array","items":{"$ref":"#/components/schemas/BulkRejectedEvent"}}},"required":["ok","accepted","deduped","rejected"]},"BulkRejectedEvent":{"type":"object","properties":{"index":{"type":"integer","minimum":0},"error_code":{"type":"string"},"error_message":{"type":"string"}},"required":["index","error_code","error_message"]},"BulkIngestRequest":{"type":"object","properties":{"events":{"type":"array","items":{},"minItems":1,"maxItems":500}},"required":["events"]},"BatchEventsResponse":{"type":"object","properties":{"accepted":{"type":"integer","minimum":0},"rejected":{"type":"array","items":{"$ref":"#/components/schemas/RejectedEvent"}}},"required":["accepted","rejected"]},"RejectedEvent":{"type":"object","properties":{"index":{"type":"integer","minimum":0},"primitive":{"type":"string"},"error_code":{"type":"string"},"error_message":{"type":"string"}},"required":["index","error_code","error_message"]},"ProblemDetails":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"detail":{"type":"string"}},"required":["type","title","status","code"]},"BatchEventsRequest":{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/BehavioralEventInput"},"minItems":1,"maxItems":500}},"required":["events"]},"BehavioralEventInput":{"type":"object","properties":{"primitive":{"type":"string","enum":["workflow.started","workflow.progressed","workflow.blocked","workflow.completed","workflow.abandoned","outcome.progressed","outcome.completed","outcome.regressed","friction.detected","collaboration.invited","collaboration.joined","collaboration.deepened","collaboration.weakened","collaboration.champion_lost","support.escalated","support.sentiment_negative","support.theme_detected","expansion.intent_detected","expansion.ceiling_hit","memory.append","session.activity"],"description":"Um dos 20 primitives canônicos · ex: workflow.blocked","example":"workflow.blocked"},"schema_version":{"type":"string","description":"Taxonomy version · default 1.0.0","example":"1.0.0"},"occurred_at":{"type":"string","format":"date-time","description":"ISO 8601 · quando o comportamento ocorreu (não enviado)","example":"2026-06-01T15:30:00Z"},"account_id":{"type":"string","format":"uuid","description":"Account do cliente final · null pra events anônimos"},"user_id":{"type":"string","maxLength":120,"description":"End-user opaco (não Holdy user)"},"session_id":{"type":"string","maxLength":120},"payload":{"type":"object","additionalProperties":{},"description":"Payload schema canônico do primitive · ex: { workflow, reason, severity } pra workflow.blocked"},"context":{"type":"object","additionalProperties":{},"description":"Metadata livre · page, device, feature flags · não validado"},"idempotency_key":{"type":"string","maxLength":120,"description":"Dedup window 24h via UNIQUE(org_id, idempotency_key)"}},"required":["primitive","occurred_at","payload"]},"MemoryResponse":{"type":"object","properties":{"accepted":{"type":"boolean"},"primitive":{"type":"string","enum":["memory.append"]}},"required":["accepted","primitive"]},"ProblemDetailsMemory":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"detail":{"type":"string"}},"required":["type","title","status","code"]},"MemoryRequest":{"type":"object","properties":{"type":{"type":"string","enum":["meeting_note","call_summary","email_thread","csm_observation","manual_note"],"description":"meeting_note · call_summary · email_thread · csm_observation · manual_note"},"content":{"type":"string","minLength":1,"maxLength":10000,"description":"Texto da memory · max 10k chars","example":"Cliente mencionou expansão pra time de finance no Q3."},"source":{"type":"string","minLength":1,"maxLength":80,"description":"Origem · ex: \"csm:augusto\", \"import:hubspot\", \"auto:summary\"","example":"csm:augusto"},"related_account_id":{"type":"string","format":"uuid","description":"Account relacionada (cliente final) · opcional"},"related_user_id":{"type":"string","maxLength":120,"description":"User relacionado (end-user opaco) · opcional"},"occurred_at":{"type":"string","format":"date-time","description":"Quando a observação foi feita · default = now"},"context":{"type":"object","additionalProperties":{}},"idempotency_key":{"type":"string","maxLength":120}},"required":["type","content","source"]},"ListTaxonomyResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/TaxonomyExtension"}},"total":{"type":"integer","minimum":0}},"required":["items","total"]},"TaxonomyExtension":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["workflow","outcome","tag","usage_metric"]},"key":{"type":"string"},"display_name":{"type":["string","null"]},"lifecycle_phase":{"type":["string","null"],"enum":["onboarding","activation","adoption","expansion","renewal","recovery",null]},"metadata":{"type":["object","null"],"additionalProperties":{}},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","kind","key","display_name","lifecycle_phase","metadata","created_at","updated_at"]},"ProblemDetailsTaxonomy":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"detail":{"type":"string"}},"required":["type","title","status","code"]},"CreateTaxonomyInput":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":80,"description":"Slug usado no payload behavioral · ex: \"invite_team\"","example":"invite_team"},"display_name":{"type":"string","maxLength":200,"description":"Nome humano · usado em UI/dashboards","example":"Convidar time"},"lifecycle_phase":{"type":"string","enum":["onboarding","activation","adoption","expansion","renewal","recovery"],"description":"Fase do ciclo de vida · enum canônico","example":"onboarding"},"metadata":{"type":"object","additionalProperties":{},"description":"Metadata livre · ex: { display_icon, color }"}},"required":["key"]},"BehaviorResponse":{"type":"object","properties":{"account_id":{"type":"string"},"window_days":{"type":"integer"},"window_start":{"type":"string"},"window_end":{"type":"string"},"total_primitives":{"type":"integer"},"by_category":{"type":"object","properties":{"workflow":{"type":"number"},"outcome":{"type":"number"},"friction":{"type":"number"},"collaboration":{"type":"number"},"support":{"type":"number"},"expansion":{"type":"number"},"memory":{"type":"number"},"session":{"type":"number"}}},"by_primitive":{"type":"object","additionalProperties":{"type":"number"}}},"required":["account_id","window_days","window_start","window_end","total_primitives","by_category","by_primitive"]},"ProblemDetailsAccounts":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"detail":{"type":"string"}},"required":["type","title","status","code"]},"RiskResponse":{"type":"object","properties":{"account_id":{"type":"string"},"score":{"type":"integer","minimum":0,"maximum":100},"level":{"type":"string","enum":["low","medium","high"]},"factors":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["friction_streak","silent_regression","workflow_blocked_rate","workflow_abandonment"]},"weight":{"type":"number","minimum":0,"maximum":1},"evidence":{"type":"string"}},"required":["kind","weight","evidence"]}},"trend_7d":{"type":"array","items":{"type":"integer","minimum":0,"maximum":100}},"window_days":{"type":"integer"}},"required":["account_id","score","level","factors","trend_7d","window_days"]},"JourneyResponse":{"type":"object","properties":{"account_id":{"type":"string"},"window_days":{"type":"integer"},"lifecycle_phase":{"type":["string","null"]},"active_workflows":{"type":"array","items":{"type":"object","properties":{"workflow":{"type":"string"},"workflow_run_id":{"type":["string","null"]},"state":{"type":"string","enum":["started","progressed","blocked","completed","abandoned"]},"started_at":{"type":["string","null"]},"last_activity_at":{"type":"string"},"duration_ms":{"type":["integer","null"]},"blocked_reason":{"type":["string","null"]},"progressed_count":{"type":"integer"}},"required":["workflow","workflow_run_id","state","started_at","last_activity_at","duration_ms","blocked_reason","progressed_count"]}},"completed_workflows":{"type":"array","items":{"type":"object","properties":{"workflow":{"type":"string"},"workflow_run_id":{"type":["string","null"]},"state":{"type":"string","enum":["started","progressed","blocked","completed","abandoned"]},"started_at":{"type":["string","null"]},"last_activity_at":{"type":"string"},"duration_ms":{"type":["integer","null"]},"blocked_reason":{"type":["string","null"]},"progressed_count":{"type":"integer"}},"required":["workflow","workflow_run_id","state","started_at","last_activity_at","duration_ms","blocked_reason","progressed_count"]}},"abandoned_workflows":{"type":"array","items":{"type":"object","properties":{"workflow":{"type":"string"},"workflow_run_id":{"type":["string","null"]},"state":{"type":"string","enum":["started","progressed","blocked","completed","abandoned"]},"started_at":{"type":["string","null"]},"last_activity_at":{"type":"string"},"duration_ms":{"type":["integer","null"]},"blocked_reason":{"type":["string","null"]},"progressed_count":{"type":"integer"}},"required":["workflow","workflow_run_id","state","started_at","last_activity_at","duration_ms","blocked_reason","progressed_count"]}},"outcomes_completed":{"type":"array","items":{"type":"object","properties":{"outcome":{"type":"string"},"completed_at":{"type":"string"},"value":{"type":["number","null"]}},"required":["outcome","completed_at","value"]}},"next_expected":{"type":"array","items":{"type":"string"}}},"required":["account_id","window_days","lifecycle_phase","active_workflows","completed_workflows","abandoned_workflows","outcomes_completed","next_expected"]},"AccountUpsertResponse":{"type":"object","properties":{"account_id":{"type":"string","format":"uuid"},"account_user_id":{"type":["string","null"],"format":"uuid"},"created":{"type":"boolean"}},"required":["account_id","account_user_id","created"]},"ProblemDetailsAccountUpsert":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"detail":{"type":"string"}},"required":["type","title","status","code"]},"AccountUpsertRequest":{"type":"object","properties":{"account":{"$ref":"#/components/schemas/AccountUpsertAccount"},"user":{"$ref":"#/components/schemas/AccountUpsertUser"}},"required":["account"]},"AccountUpsertAccount":{"type":"object","properties":{"external_id":{"type":"string","minLength":1,"maxLength":200,"description":"ID do cliente (string opaca) · resolvido via customer_identities","example":"acct_xyz123"},"name":{"type":"string","minLength":1,"maxLength":200},"logo_url":{"type":"string","maxLength":500,"format":"uri"},"domain":{"type":"string","maxLength":200},"plan":{"type":"string","maxLength":100,"description":"Nome do plano · resolvido pra plan_id via org_plans (auto-create)"},"plan_monthly_ai_quota":{"type":"number","exclusiveMinimum":0,"description":"Cota mensal de IA do PLANO (tokens ou a unidade do seu produto) · grava em org_plans junto do plan. Consumo ÷ cota vira o sinal de expansão."},"mrr":{"type":"number","minimum":0},"contract_start":{"type":"string","format":"date"},"contract_end":{"type":"string","format":"date"},"lifecycle_stage":{"type":"string","enum":["onboarding","adoption","expansion","renewal","churned"]},"traits":{"type":"object","additionalProperties":{}}},"required":["external_id"]},"AccountUpsertUser":{"type":"object","properties":{"external_id":{"type":"string","minLength":1,"maxLength":200},"email":{"type":"string","maxLength":200,"format":"email"},"name":{"type":"string","maxLength":200},"job_title":{"type":"string","maxLength":200},"role":{"type":"string","enum":["decision_maker","champion","admin","user","unknown"]}},"required":["external_id"]},"AccountStateResponse":{"type":"object","properties":{"account_id":{"type":"string","format":"uuid"},"account_user_id":{"type":["string","null"],"format":"uuid"},"created":{"type":"boolean"},"usage_upserted":{"type":"integer","minimum":0}},"required":["account_id","account_user_id","created","usage_upserted"]},"ProblemDetailsAccountState":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"detail":{"type":"string"}},"required":["type","title","status","code"]},"AccountStateRequest":{"type":"object","properties":{"account":{"$ref":"#/components/schemas/AccountStateAccount"},"user":{"$ref":"#/components/schemas/AccountStateUser"},"users_active":{"type":"integer","minimum":0,"description":"Shortcut · grava gauge metric_key=\"active_users_current\". Equivalente a passar em usage[]."},"usage":{"type":"array","items":{"$ref":"#/components/schemas/AccountStateUsageGauge"},"maxItems":100}},"required":["account"]},"AccountStateAccount":{"type":"object","properties":{"external_id":{"type":"string","minLength":1,"maxLength":200},"name":{"type":"string","minLength":1,"maxLength":200},"logo_url":{"type":"string","maxLength":500,"format":"uri"},"domain":{"type":"string","maxLength":200},"plan":{"type":"string","maxLength":100},"mrr":{"type":"number","minimum":0},"contract_start":{"type":"string","format":"date"},"contract_end":{"type":"string","format":"date"},"lifecycle_stage":{"type":"string","enum":["onboarding","adoption","expansion","renewal","churned"]},"traits":{"type":"object","additionalProperties":{}}},"required":["external_id"]},"AccountStateUser":{"type":"object","properties":{"external_id":{"type":"string","minLength":1,"maxLength":200},"email":{"type":"string","maxLength":200,"format":"email"},"name":{"type":"string","maxLength":200},"job_title":{"type":"string","maxLength":200},"role":{"type":"string","enum":["decision_maker","champion","admin","user","unknown"]}},"required":["external_id"]},"AccountStateUsageGauge":{"type":"object","properties":{"metric_key":{"type":"string","minLength":1,"maxLength":80,"description":"Slug do gauge · ex: \"credits_used\", \"seats_used\", \"api_calls_30d\". Auto-register.","example":"credits_used"},"current_value":{"type":"number","description":"Valor atual do gauge no momento do sync.","example":7500},"limit_value":{"type":"number","description":"Teto quando aplicável · ex: creditsLimit=10000. Omita pra gauges sem teto."},"unit":{"type":"string","maxLength":40,"description":"Display label · \"credits\", \"seats\", \"gb\". Não usado em cálculo."},"user_external_id":{"type":"string","maxLength":200,"description":"Gauge por seat · default empty = gauge por conta inteira."},"measured_at":{"type":"string","format":"date-time"}},"required":["metric_key","current_value"]},"EvaluateDecisionResponse":{"type":"object","properties":{"decision_id":{"type":"string","format":"uuid"},"decision_type":{"type":"string","enum":["intervention","briefing","cs_task","track_journey","no_action"]},"decision_payload":{"type":"object","additionalProperties":{}},"rule_key":{"type":"string"},"confidence":{"type":"number","minimum":0,"maximum":1},"reason":{"type":"string"},"decided_at":{"type":"string"}},"required":["decision_id","decision_type","decision_payload","rule_key","confidence","reason","decided_at"]},"ProblemDetailsDecisions":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"detail":{"type":"string"}},"required":["type","title","status","code"]},"EvaluateDecisionRequest":{"type":"object","properties":{"account_id":{"type":"string","format":"uuid","description":"Account do cliente final"},"current_workflow":{"type":"string","maxLength":80,"description":"Workflow ativo agora (se houver)","example":"invite_team"},"recent_primitives":{"type":"array","items":{"type":"object","properties":{"primitive":{"type":"string","enum":["workflow.started","workflow.progressed","workflow.blocked","workflow.completed","workflow.abandoned","outcome.progressed","outcome.completed","outcome.regressed","friction.detected","collaboration.invited","collaboration.joined","collaboration.deepened","collaboration.weakened","collaboration.champion_lost","support.escalated","support.sentiment_negative","support.theme_detected","expansion.intent_detected","expansion.ceiling_hit","memory.append","session.activity"]},"payload":{"type":"object","additionalProperties":{}},"occurred_at":{"type":"string","format":"date-time"}},"required":["primitive","payload","occurred_at"]},"maxItems":20,"description":"Eventos recentes do user (max 20) · informa decisão. Idealmente últimos 7d."},"recent_sentiment":{"type":"string","enum":["positivo","neutro","negativo","urgente"],"description":"Sentiment recente detectado · informa rules de escalation"},"consumer":{"type":"string","enum":["ui","csm","agent"],"description":"Quem está consultando · \"ui\" = SDK no produto do cliente · default ui"}},"required":["account_id"]},"DecisionOutcomeResponse":{"type":"object","properties":{"decision_id":{"type":"string","format":"uuid"},"outcome":{"type":"string","enum":["executed","dismissed","converted","no_show","failed"]},"recorded":{"type":"boolean"}},"required":["decision_id","outcome","recorded"]},"DecisionOutcomeRequest":{"type":"object","properties":{"outcome":{"type":"string","enum":["executed","dismissed","converted","no_show","failed"]},"metadata":{"type":"object","additionalProperties":{},"description":"Contexto adicional · ex: { user_clicked: true, time_to_react_ms: 12000 }"}},"required":["outcome"]},"RuntimeConfigResponse":{"type":"object","properties":{"api_version":{"type":"string"},"taxonomy_version":{"type":"string"},"organization_id":{"type":"string"},"taxonomy":{"type":"object","properties":{"workflows":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"display_name":{"type":["string","null"]},"lifecycle_phase":{"type":["string","null"]}},"required":["key","display_name","lifecycle_phase"]}},"outcomes":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"display_name":{"type":["string","null"]},"lifecycle_phase":{"type":["string","null"]}},"required":["key","display_name","lifecycle_phase"]}}},"required":["workflows","outcomes"]},"thresholds":{"type":"object","properties":{"dormancy_days":{"type":"number"},"low_usage_pct":{"type":"number"},"usage_drop_alert_pct":{"type":"number"},"usage_drop_severe_pct":{"type":"number"},"active_users_collapse_pct":{"type":"number"},"source":{"type":"string"}},"required":["dormancy_days","low_usage_pct","usage_drop_alert_pct","usage_drop_severe_pct","active_users_collapse_pct","source"]},"heuristics":{"type":"object","properties":{"rage_click_count":{"type":"number"},"rage_click_window_ms":{"type":"number"},"idle_confusion_ms":{"type":"number"},"dead_click_threshold_ms":{"type":"number"},"retry_storm_count":{"type":"number"},"retry_storm_window_ms":{"type":"number"},"session_timeout_ms":{"type":"number"}},"required":["rage_click_count","rage_click_window_ms","idle_confusion_ms","dead_click_threshold_ms","retry_storm_count","retry_storm_window_ms","session_timeout_ms"]},"features":{"type":"object","properties":{"auto_attribution":{"type":"boolean"},"interventions_enabled":{"type":"boolean"},"consent_required":{"type":"boolean"}},"required":["auto_attribution","interventions_enabled","consent_required"]},"theme":{"type":"object","properties":{"primary_color":{"type":"string"},"font_family":{"type":"string"},"border_radius_px":{"type":"number"},"position_offset_px":{"type":"number"}},"required":["primary_color","font_family","border_radius_px","position_offset_px"]}},"required":["api_version","taxonomy_version","organization_id","taxonomy","thresholds","heuristics","features","theme"]},"ProblemDetailsRuntime":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"detail":{"type":"string"}},"required":["type","title","status","code"]},"BehaviorCandidatesListResponse":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"organization_id":{"type":"string","format":"uuid"},"count":{"type":"integer"},"candidates":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"proposed_name":{"type":"string"},"proposed_definition":{"type":"string"},"business_goal":{"type":["string","null"]},"canonical_name":{"type":["string","null"]},"cluster_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"proposed_edges":{"type":"array","items":{"type":"object","properties":{"to_candidate_id":{"type":"string","format":"uuid"},"relation":{"type":"string"},"confidence":{"type":"number"}},"required":["to_candidate_id","relation","confidence"]}},"template_id":{"type":["string","null"],"format":"uuid"},"confidence":{"type":"number"},"status":{"type":"string","enum":["proposed","approved","rejected","superseded_by"]},"source_agent":{"type":"string"},"reviewed_at":{"type":["string","null"]},"reviewed_by":{"type":["string","null"],"format":"uuid"},"created_at":{"type":"string"}},"required":["id","proposed_name","proposed_definition","business_goal","canonical_name","cluster_ids","proposed_edges","template_id","confidence","status","source_agent","reviewed_at","reviewed_by","created_at"]}}},"required":["ok","organization_id","count","candidates"]},"ProblemDetailsBehaviorCandidates":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"detail":{"type":"string"}},"required":["type","title","status","code"]},"BehaviorCandidateApproveResponse":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"behavior":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"behavior_key":{"type":"string"},"version":{"type":"integer"},"name":{"type":"string"}},"required":["id","behavior_key","version","name"]},"already_promoted":{"type":"boolean"},"behavior_id":{"type":"string","format":"uuid"},"edges_materialized":{"type":"integer"},"edges_pending":{"type":"integer"}},"required":["ok","edges_materialized","edges_pending"]},"BehaviorCandidateApproveConflict":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"detail":{"type":"string"},"conflict":{"type":"object","properties":{"behavior_key":{"type":"string"},"existing_behavior_id":{"type":"string","format":"uuid"},"existing_version":{"type":"integer"}},"required":["behavior_key","existing_behavior_id","existing_version"]},"hint":{"type":"string"}},"required":["type","title","status","code","detail"]},"BehaviorCandidateApproveBody":{"type":"object","properties":{"supersede":{"type":"boolean","default":false,"description":"Permite substituir behavior existente com mesmo canonical_name (deprecate old, criar N+1)"},"overrides":{"type":"object","properties":{"name":{"type":"string","minLength":1},"definition":{"type":"string","minLength":10},"business_goal":{"type":"string"},"required_cluster_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"optional_cluster_ids":{"type":"array","items":{"type":"string","format":"uuid"}}},"description":"Tune o candidate antes de promover — cliente-final define significado, LLM só propôs"},"actor_user_id":{"type":["string","null"],"format":"uuid","description":"Audit trail · quem aprovou (opcional em ambiente admin)"}}},"BehaviorCandidateRejectResponse":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"]},"BehaviorCandidateRejectBody":{"type":"object","properties":{"actor_user_id":{"type":["string","null"],"format":"uuid"}}},"EvidenceResponse":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"target_kind":{"type":"string","enum":["signal","insight","opportunity"]},"target_id":{"type":"string","format":"uuid"},"count":{"type":"integer"},"evidence":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["replay","raw_events","metrics_snapshot","timeline"]},"target_kind":{"type":"string","enum":["signal","insight","opportunity"]},"target_id":{"type":"string","format":"uuid"},"payload":{"type":"object","additionalProperties":{}},"created_at":{"type":"string"}},"required":["id","kind","target_kind","target_id","payload","created_at"]}}},"required":["ok","target_kind","target_id","count","evidence"]},"ProblemDetailsEvidence":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"detail":{"type":"string"}},"required":["type","title","status","code"]},"OpportunitiesListResponse":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"count":{"type":"integer"},"next_cursor":{"type":["string","null"]},"opportunities":{"type":"array","items":{"$ref":"#/components/schemas/OpportunityRow"}}},"required":["ok","count","next_cursor","opportunities"]},"OpportunityRow":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["open","in_progress","resolved","dismissed"]},"origin_kind":{"type":"string"},"origin_signal_id":{"type":["string","null"],"format":"uuid"},"origin_insight_id":{"type":["string","null"],"format":"uuid"},"impact_estimate":{},"affected_cohort_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"affected_account_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"evidence_ref":{"type":"array","items":{"type":"string","format":"uuid"}},"created_at":{"type":"string"}},"required":["id","title","description","status","origin_kind","origin_signal_id","origin_insight_id","affected_cohort_ids","affected_account_ids","evidence_ref","created_at"]},"ProblemDetailsIntelligence":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"detail":{"type":"string"}},"required":["type","title","status","code"]},"OpportunityResponse":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"opportunity":{"$ref":"#/components/schemas/OpportunityRow"}},"required":["ok","opportunity"]},"SignalsListResponse":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"count":{"type":"integer"},"next_cursor":{"type":["string","null"]},"signals":{"type":"array","items":{"$ref":"#/components/schemas/SignalRow"}}},"required":["ok","count","next_cursor","signals"]},"SignalRow":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"type":{"type":"string"},"severity":{"type":"string"},"status":{"type":"string"},"advisory":{"type":"boolean"},"behavior_id":{"type":["string","null"],"format":"uuid"},"detector_id":{"type":"string","format":"uuid"},"affected_scope_kind":{"type":"string"},"affected_scope_id":{"type":["string","null"],"format":"uuid"},"occurrences":{"type":"integer"},"impact":{},"evidence_ref":{"type":"array","items":{"type":"string","format":"uuid"}},"detected_at":{"type":"string"},"first_detected_at":{"type":["string","null"]},"expires_at":{"type":"string"}},"required":["id","name","description","type","severity","status","advisory","behavior_id","detector_id","affected_scope_kind","affected_scope_id","occurrences","evidence_ref","detected_at","first_detected_at","expires_at"]},"MetricCompositionsListResponse":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"organization_id":{"type":"string","format":"uuid"},"count":{"type":"integer"},"compositions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"metric":{"type":"string","enum":["activation","adoption","expansion","revenue","efficiency","time_to_value","aha_rate"]},"definition_names":{"type":"array","items":{"type":"string"}},"version":{"type":"integer"},"created_at":{"type":"string"},"deprecated_at":{"type":["string","null"]}},"required":["id","metric","definition_names","version","created_at","deprecated_at"]}}},"required":["ok","organization_id","count","compositions"]},"ProblemDetailsMetricCompositions":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"detail":{"type":"string"}},"required":["type","title","status","code"]},"MetricCompositionCreateResponse":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"composition":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"metric":{"type":"string","enum":["activation","adoption","expansion","revenue","efficiency","time_to_value","aha_rate"]},"definition_names":{"type":"array","items":{"type":"string"}},"version":{"type":"integer"},"created_at":{"type":"string"},"deprecated_at":{"type":["string","null"]}},"required":["id","metric","definition_names","version","created_at","deprecated_at"]},"superseded_id":{"type":["string","null"],"format":"uuid"}},"required":["ok","composition","superseded_id"]},"MetricCompositionCreateBody":{"type":"object","properties":{"organization_id":{"type":"string","format":"uuid"},"metric":{"type":"string","enum":["activation","adoption","expansion","revenue","efficiency","time_to_value","aha_rate"],"description":"Métrica componível · frequency/usage/retention são derived v1, não aceitas"},"definition_names":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"description":"Nomes das behavior definitions (AND) que definem a métrica · ADR-0005"}},"required":["organization_id","metric","definition_names"]},"CohortsListResponse":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"organization_id":{"type":"string","format":"uuid"},"count":{"type":"integer"},"cohorts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":["string","null"]},"definition":{},"version":{"type":"integer"},"status":{"type":"string"},"created_at":{"type":"string"}},"required":["id","name","description","version","status","created_at"]}}},"required":["ok","organization_id","count","cohorts"]},"ProblemDetailsCohorts":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"detail":{"type":"string"}},"required":["type","title","status","code"]},"CohortPreviewResponse":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"matched":{"type":"integer"},"sample_account_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"as_of":{"type":"string"}},"required":["ok","matched","sample_account_ids","as_of"]},"CohortPreviewBody":{"type":"object","properties":{"organization_id":{"type":"string","format":"uuid"},"definition":{"type":"object","properties":{"grammar_version":{"type":"number","enum":[1]},"population":{"type":"object","properties":{"plans":{"type":"array","items":{"type":"string","minLength":1,"maxLength":120},"maxItems":50},"lifecycle_stages":{"type":"array","items":{"type":"string","minLength":1,"maxLength":120},"maxItems":50},"mrr_min":{"type":"number","minimum":0},"mrr_max":{"type":"number","minimum":0}},"additionalProperties":false},"temporal":{"type":"object","properties":{"account_age_days_min":{"type":"integer","minimum":0,"maximum":3650},"account_age_days_max":{"type":"integer","exclusiveMinimum":0,"maximum":3650}},"additionalProperties":false},"behavior":{"type":"object","properties":{"definition_names":{"type":"array","items":{"type":"string","minLength":1,"maxLength":120},"minItems":1,"maxItems":50},"state":{"type":"string","enum":["completed","in_progress","not_started","expired"],"default":"completed"},"within_days_of_signup":{"type":"integer","exclusiveMinimum":0,"maximum":3650}},"required":["definition_names"],"additionalProperties":false},"acquisition":{"type":"object","properties":{"utm_sources":{"type":"array","items":{"type":"string","minLength":1,"maxLength":120},"maxItems":50},"utm_mediums":{"type":"array","items":{"type":"string","minLength":1,"maxLength":120},"maxItems":50},"referrer_hosts":{"type":"array","items":{"type":"string","minLength":1,"maxLength":120},"maxItems":50}},"additionalProperties":false}},"required":["grammar_version"],"additionalProperties":false},"as_of":{"type":"string","format":"date-time","description":"Data de referência · default agora. Idade da conta é medida contra ela."}},"required":["organization_id","definition"]},"CohortCreateResponse":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"cohort":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":["string","null"]},"definition":{},"version":{"type":"integer"},"status":{"type":"string"},"created_at":{"type":"string"}},"required":["id","name","description","version","status","created_at"]},"superseded_id":{"type":["string","null"],"format":"uuid"},"created":{"type":"boolean"},"matched":{"type":["integer","null"]},"as_of":{"type":"string"}},"required":["ok","cohort","superseded_id","created","matched","as_of"]},"CohortCreateBody":{"type":"object","properties":{"organization_id":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":120},"description":{"type":"string","maxLength":500},"definition":{"type":"object","properties":{"grammar_version":{"type":"number","enum":[1]},"population":{"type":"object","properties":{"plans":{"type":"array","items":{"type":"string","minLength":1,"maxLength":120},"maxItems":50},"lifecycle_stages":{"type":"array","items":{"type":"string","minLength":1,"maxLength":120},"maxItems":50},"mrr_min":{"type":"number","minimum":0},"mrr_max":{"type":"number","minimum":0}},"additionalProperties":false},"temporal":{"type":"object","properties":{"account_age_days_min":{"type":"integer","minimum":0,"maximum":3650},"account_age_days_max":{"type":"integer","exclusiveMinimum":0,"maximum":3650}},"additionalProperties":false},"behavior":{"type":"object","properties":{"definition_names":{"type":"array","items":{"type":"string","minLength":1,"maxLength":120},"minItems":1,"maxItems":50},"state":{"type":"string","enum":["completed","in_progress","not_started","expired"],"default":"completed"},"within_days_of_signup":{"type":"integer","exclusiveMinimum":0,"maximum":3650}},"required":["definition_names"],"additionalProperties":false},"acquisition":{"type":"object","properties":{"utm_sources":{"type":"array","items":{"type":"string","minLength":1,"maxLength":120},"maxItems":50},"utm_mediums":{"type":"array","items":{"type":"string","minLength":1,"maxLength":120},"maxItems":50},"referrer_hosts":{"type":"array","items":{"type":"string","minLength":1,"maxLength":120},"maxItems":50}},"additionalProperties":false}},"required":["grammar_version"],"additionalProperties":false}},"required":["organization_id","name","definition"]},"StateProfilesListResponse":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"organization_id":{"type":"string","format":"uuid"},"count":{"type":"integer"},"profiles":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":["string","null"]},"target_state":{"type":"string"},"definition":{},"priority":{"type":"integer"},"version":{"type":"integer"},"status":{"type":"string"},"created_at":{"type":"string"}},"required":["id","name","description","target_state","priority","version","status","created_at"]}}},"required":["ok","organization_id","count","profiles"]},"ProblemDetailsStateProfiles":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"detail":{"type":"string"}},"required":["type","title","status","code"]},"StateProfileCreateResponse":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"profile":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":["string","null"]},"target_state":{"type":"string"},"definition":{},"priority":{"type":"integer"},"version":{"type":"integer"},"status":{"type":"string"},"created_at":{"type":"string"}},"required":["id","name","description","target_state","priority","version","status","created_at"]},"superseded_id":{"type":["string","null"],"format":"uuid"},"created":{"type":"boolean"}},"required":["ok","profile","superseded_id","created"]},"StateProfileCreateBody":{"type":"object","properties":{"organization_id":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":120},"description":{"type":"string","maxLength":500},"target_state":{"type":"string","enum":["adopting","value_realized","expanding","friction","declining","disengaged","at_risk"],"description":"Estado atribuído quando o profile bate · new/activating não são configuráveis"},"definition":{"type":"object","properties":{"grammar_version":{"type":"number","enum":[1]},"conditions":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["metric_threshold"]},"metric":{"type":"string","minLength":1},"operator":{"type":"string","enum":["lt","lte","gt","gte"]},"value":{"type":"number"},"minimum_sample":{"type":"integer","minimum":0,"default":1}},"required":["kind","metric","operator","value"]},{"type":"object","properties":{"kind":{"type":"string","enum":["metric_change"]},"metric":{"type":"string","minLength":1},"direction":{"type":"string","enum":["drop","rise"]},"pct":{"type":"number","exclusiveMinimum":0,"maximum":100},"minimum_sample":{"type":"integer","minimum":0,"default":1}},"required":["kind","metric","direction","pct"]},{"type":"object","properties":{"kind":{"type":"string","enum":["behavior_state"]},"definition_name":{"type":"string","minLength":1},"state":{"type":"string","enum":["not_started","in_progress","completed","expired"]},"for_days":{"type":"integer","exclusiveMinimum":0}},"required":["kind","definition_name","state"]},{"type":"object","properties":{"kind":{"type":"string","enum":["inactivity"]},"days_gte":{"type":"integer","exclusiveMinimum":0}},"required":["kind","days_gte"]}]},"minItems":1,"maxItems":10},"evaluation_policy":{"type":"object","properties":{"match":{"type":"string","enum":["all_of","any_of"],"default":"all_of"},"consecutive_windows":{"type":"integer","exclusiveMinimum":0}},"default":{"match":"all_of"}}},"required":["grammar_version","conditions"]},"priority":{"type":"integer","minimum":0,"maximum":10000,"description":"Menor primeiro · empate resolve por nome (decisão estável entre ticks)"}},"required":["organization_id","name","target_state","definition"]},"InstrumentationPlan":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"event":{"type":"string","maxLength":80,"pattern":"^[a-z][a-z0-9_]*\\.[a-z][a-z0-9_]*$"},"purpose":{"type":"string","minLength":10,"maxLength":240},"lifecycle_phase":{"type":"string","enum":["onboarding","activation","adoption","expansion","renewal","recovery"]},"file":{"type":"string","minLength":1,"maxLength":400},"anchor":{"type":"string","minLength":8,"maxLength":400},"position":{"type":"string","enum":["before","after"]},"snippet":{"type":"string","minLength":8,"maxLength":600},"properties":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","maxLength":60},"example":{"type":"string","maxLength":120}},"required":["name","example"]},"maxItems":6},"confidence":{"type":"string","enum":["alta","media","baixa"]}},"required":["event","purpose","lifecycle_phase","file","anchor","position","snippet","properties","confidence"]},"maxItems":20},"summary":{"type":"string","minLength":10,"maxLength":600},"metrics":{"type":"array","items":{"$ref":"#/components/schemas/InstrumentationMetricReadiness"},"default":[]}},"required":["events","summary"]},"InstrumentationMetricReadiness":{"type":"object","properties":{"metric":{"type":"string","enum":["activation","adoption","aha_rate","time_to_value"]},"label":{"type":"string"},"ready":{"type":"boolean"},"missing":{"type":"array","items":{"type":"string"}},"covering":{"type":"array","items":{"type":"string"}},"needs_choice":{"type":"string"}},"required":["metric","label","ready","missing","covering"]},"ProblemDetailsInstrumentation":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"detail":{"type":"string"}},"required":["type","title","status","code"]},"InstrumentationPlanInput":{"type":"object","properties":{"framework":{"type":"string","minLength":1,"maxLength":40,"example":"next-app"},"sdk_style":{"type":"string","enum":["npm","script"],"default":"npm"},"max_events":{"type":"integer","minimum":3,"maximum":20,"default":12},"files":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","minLength":1,"maxLength":400},"kind":{"type":"string","enum":["page","route","component","api","server","other"]},"excerpt":{"type":"string","maxLength":6000}},"required":["path","kind","excerpt"]},"minItems":1,"maxItems":160}},"required":["framework","files"]},"ConsumptionResponse":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"organization_id":{"type":"string","format":"uuid"},"window_days":{"type":"integer"},"plan":{"type":"object","properties":{"key":{"type":["string","null"]},"tracked_users":{"type":["integer","null"],"description":"null = não medido neste ambiente, que é diferente de zero."},"cap":{"type":["integer","null"]},"usage_ratio":{"type":["number","null"]}},"required":["key","tracked_users","cap","usage_ratio"]},"ai":{"type":"object","properties":{"tokens_month":{"type":["integer","null"],"description":"Tokens de IA no mês calendário corrente · null = medição indisponível."},"cap":{"type":["integer","null"],"description":"Teto mensal do plano · null = sem teto."},"usage_ratio":{"type":["number","null"]}},"required":["tokens_month","cap","usage_ratio"]},"ingestion":{"type":"object","properties":{"events_30d":{"type":"integer"},"active_days_30d":{"type":"integer"},"last_event_at":{"type":["string","null"]}},"required":["events_30d","active_days_30d","last_event_at"]},"accounts":{"type":["array","null"],"items":{"type":"object","properties":{"account_id":{"type":"string","format":"uuid"},"account_name":{"type":["string","null"]},"events_30d":{"type":"integer"},"last_event_at":{"type":["string","null"]},"people":{"type":"integer","description":"Identidades canônicas da conta."},"ai_tokens":{"type":"number","description":"Consumo de IA da conta na janela (properties.ai_tokens somadas) · 0 = sem instrumentação de consumo."},"ai_cost_usd":{"type":"number"}},"required":["account_id","account_name","events_30d","last_event_at","people","ai_tokens","ai_cost_usd"]},"description":"Presente só com scope=account. null no agregado."}},"required":["ok","organization_id","window_days","plan","ai","ingestion","accounts"]},"ProblemDetailsConsumption":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"detail":{"type":"string"}},"required":["type","title","status","code"]}},"parameters":{}},"paths":{"/api/v1/events":{"post":{"operationId":"postEvents","security":[{"bearerAuth":[]}],"tags":["Events"],"summary":"Ingest event (single)","description":"Recebe UM evento e grava em events (Entry layer). Pipeline downstream (Data → Knowledge → Detection → Intelligence → Execution) roda async via jobs.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestEventInput"}}}},"responses":{"202":{"description":"Event accepted for processing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestEventResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestErrorResponse"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestErrorResponse"}}}}}}},"/api/v1/events/bulk":{"post":{"operationId":"postEventsBulk","security":[{"bearerAuth":[]}],"tags":["Events"],"summary":"Ingest events (bulk · até 500)","description":"Mesma semântica do single com partial accept: 1 event inválido não aborta o batch (rejected[i].index aponta qual). Dedupe via external_id — re-poll da mesma janela pelos adapters conta em `deduped`, nunca duplica.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkIngestRequest"}}}},"responses":{"202":{"description":"Batch accepted · accepted + deduped + rejected per-event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkIngestResponse"}}}},"400":{"description":"Validation error (top-level shape)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestErrorResponse"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestErrorResponse"}}}}}}},"/api/v1/events/batch":{"post":{"operationId":"postEventsBatch","tags":["Events"],"summary":"Ingest batch de behavioral primitives","description":"Envia até 500 primitives semânticos por chamada. Validação per-event · partial accept (1 event ruim não aborta o batch). Idempotency via campo idempotency_key (UNIQUE 24h).","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchEventsRequest"}}}},"responses":{"200":{"description":"Batch processed · accepted + rejected per-event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchEventsResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Insufficient scope (events:write required)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/api/v1/memory":{"post":{"operationId":"postMemory","tags":["Memory"],"summary":"Persiste knowledge memory.append","description":"Adiciona uma memory (note, call summary, observation) ao behavior graph. Mesma tabela que primitives behavioral, mas categoria semântica separada · usado pelo reasoning + agents pra contextualizar decisões.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryRequest"}}}},"responses":{"200":{"description":"Memory persistida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsMemory"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsMemory"}}}},"403":{"description":"Insufficient scope (events:write required)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsMemory"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsMemory"}}}},"500":{"description":"Storage failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsMemory"}}}}}}},"/api/v1/taxonomy/workflows":{"get":{"operationId":"getTaxonomyWorkflows","tags":["Taxonomy"],"summary":"Lista workflows declarados","description":"Retorna todos os workflows que a org declarou via POST. Usado pelo SDK em init pra bootstrap.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Workflows declarados","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListTaxonomyResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsTaxonomy"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsTaxonomy"}}}},"500":{"description":"Storage failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsTaxonomy"}}}}}},"post":{"operationId":"postTaxonomyWorkflows","tags":["Taxonomy"],"summary":"Declara/atualiza workflow (upsert)","description":"Cliente PRECISA declarar workflow antes de emitir workflow.started({workflow: \"X\"}). Idempotente: chamar com mesma key atualiza display_name/lifecycle_phase/metadata.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTaxonomyInput"}}}},"responses":{"200":{"description":"Workflow declarado/atualizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxonomyExtension"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsTaxonomy"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsTaxonomy"}}}},"403":{"description":"Insufficient scope (taxonomy:write required)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsTaxonomy"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsTaxonomy"}}}},"500":{"description":"Storage failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsTaxonomy"}}}}}}},"/api/v1/taxonomy/outcomes":{"get":{"operationId":"getTaxonomyOutcomes","tags":["Taxonomy"],"summary":"Lista outcomes declarados","description":"Outcomes são resultados de longo prazo (não eventos). Raros · esperado 5-15 por org total.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Outcomes declarados","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListTaxonomyResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsTaxonomy"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsTaxonomy"}}}},"500":{"description":"Storage failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsTaxonomy"}}}}}},"post":{"operationId":"postTaxonomyOutcomes","tags":["Taxonomy"],"summary":"Declara/atualiza outcome (upsert)","description":"Cliente PRECISA declarar outcome antes de emitir outcome.completed({outcome: \"X\"}). Idempotente.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTaxonomyInput"}}}},"responses":{"200":{"description":"Outcome declarado/atualizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxonomyExtension"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsTaxonomy"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsTaxonomy"}}}},"403":{"description":"Insufficient scope (taxonomy:write required)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsTaxonomy"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsTaxonomy"}}}},"500":{"description":"Storage failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsTaxonomy"}}}}}}},"/api/v1/accounts/{id}/behavior":{"get":{"operationId":"getAccountsByIdBehavior","tags":["Behavior"],"summary":"Aggregate de behavioral primitives por categoria + primitive","description":"Retorna contagens agregadas dos primitives canônicos emitidos pra uma account na janela. Base pra derivação de risk/journey · SDK consume pra dashboards.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"UUID da account","example":"acc_xyz123-4567-89ab-cdef-1234567890ab"},"required":true,"description":"UUID da account","name":"id","in":"path"},{"schema":{"type":"string","enum":["7d","30d","90d"],"description":"Janela temporal · default 30d","example":"30d"},"required":false,"description":"Janela temporal · default 30d","name":"window","in":"query"}],"responses":{"200":{"description":"Aggregate retornado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BehaviorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsAccounts"}}}},"403":{"description":"Insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsAccounts"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsAccounts"}}}},"500":{"description":"Storage failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsAccounts"}}}}}}},"/api/v1/accounts/{id}/risk":{"get":{"operationId":"getAccountsByIdRisk","tags":["Risk"],"summary":"Risk score 0-100 derivado server-side","description":"Risk NUNCA é primitive client-emitted · taxonomy v1 garante. Holdy deriva de friction.detected + silent_regression + workflow_blocked_rate + workflow_abandonment.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"UUID da account","example":"acc_xyz123-4567-89ab-cdef-1234567890ab"},"required":true,"description":"UUID da account","name":"id","in":"path"},{"schema":{"type":"string","enum":["7d","30d","90d"],"description":"Janela temporal · default 30d","example":"30d"},"required":false,"description":"Janela temporal · default 30d","name":"window","in":"query"}],"responses":{"200":{"description":"Risk assessment retornado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsAccounts"}}}},"403":{"description":"Insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsAccounts"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsAccounts"}}}},"500":{"description":"Storage failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsAccounts"}}}}}}},"/api/v1/accounts/{id}/journey":{"get":{"operationId":"getAccountsByIdJourney","tags":["Journey"],"summary":"Workflow progression timeline","description":"Agrega workflow.* primitives por workflow_run_id em runs com state final. Mostra active/completed/abandoned + outcomes alcançados.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"UUID da account","example":"acc_xyz123-4567-89ab-cdef-1234567890ab"},"required":true,"description":"UUID da account","name":"id","in":"path"},{"schema":{"type":"string","enum":["7d","30d","90d"],"description":"Janela temporal · default 30d","example":"30d"},"required":false,"description":"Janela temporal · default 30d","name":"window","in":"query"}],"responses":{"200":{"description":"Journey retornado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JourneyResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsAccounts"}}}},"403":{"description":"Insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsAccounts"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsAccounts"}}}},"500":{"description":"Storage failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsAccounts"}}}}}}},"/api/v1/accounts/upsert":{"post":{"operationId":"postAccountsUpsert","tags":["Accounts"],"summary":"Upsert COALESCE de account+user vindo do SDK identify()","description":"Enriquece account e opcionalmente account_user a partir do SDK. COALESCE rígido: campos preenchidos no wizard manual nunca são sobrescritos. Plan name vira plan_id via org_plans (auto-create). Idempotente por (org, source=sdk, external_id).","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountUpsertRequest"}}}},"responses":{"200":{"description":"Account upserted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountUpsertResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsAccountUpsert"}}}},"403":{"description":"Insufficient scope (accounts:write required)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsAccountUpsert"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsAccountUpsert"}}}},"500":{"description":"Storage failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsAccountUpsert"}}}}}}},"/api/v1/accounts/state":{"post":{"operationId":"postAccountsState","tags":["Accounts"],"summary":"State sync · upsert account + usage gauges vindo do backend SDK","description":"Holdy.sync() bate aqui. Upserta account (COALESCE wizard-safe via /accounts/upsert helper) + gauges de uso em account_usage_snapshots (UPSERT por metric_key). Metric keys novas auto-register.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountStateRequest"}}}},"responses":{"200":{"description":"State synced","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountStateResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsAccountState"}}}},"403":{"description":"Insufficient scope (accounts:write required)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsAccountState"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsAccountState"}}}},"500":{"description":"Storage failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsAccountState"}}}}}}},"/api/v1/decisions/evaluate":{"post":{"operationId":"postDecisionsEvaluate","tags":["Runtime"],"summary":"Pede uma decision contextual · runtime bidirectional layer","description":"SDK envia context (workflow atual + primitives recentes + sentiment) · backend roda rules + retorna intervention pronta pra UI ou cs_task pro CSM. Resposta inclui decision_id pra reportar outcome depois (POST /v1/decisions/{id}/outcome).","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvaluateDecisionRequest"}}}},"responses":{"200":{"description":"Decision retornada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvaluateDecisionResponse"}}}},"400":{"description":"Validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsDecisions"}}}},"401":{"description":"Auth","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsDecisions"}}}},"403":{"description":"Scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsDecisions"}}}},"429":{"description":"Rate limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsDecisions"}}}},"500":{"description":"Storage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsDecisions"}}}}}}},"/api/v1/decisions/{decision_id}/outcome":{"post":{"operationId":"postDecisionsByDecisionIdOutcome","tags":["Runtime"],"summary":"Reporta outcome de uma decision · fecha o loop bidirecional","description":"SDK reporta o que aconteceu com a decision: executed (cliente fez ação), dismissed (fechou), converted (workflow.completed depois), no_show (SDK desconectou), failed (erro técnico). Idempotente · só registra primeira vez.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"decision_id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecisionOutcomeRequest"}}}},"responses":{"200":{"description":"Outcome registrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecisionOutcomeResponse"}}}},"400":{"description":"Validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsDecisions"}}}},"401":{"description":"Auth","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsDecisions"}}}},"403":{"description":"Scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsDecisions"}}}},"429":{"description":"Rate limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsDecisions"}}}},"500":{"description":"Storage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsDecisions"}}}}}}},"/api/v1/runtime/config":{"get":{"operationId":"getRuntimeConfig","tags":["Runtime"],"summary":"SDK bootstrap config · workflows + outcomes + thresholds + heuristics","description":"Chamado pelo SDK no init() · retorna tudo que ele precisa pra calibrar comportamento per-org. Cache local recomendado: 1h. Re-validate em background.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Config retornado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RuntimeConfigResponse"}}}},"401":{"description":"Auth","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsRuntime"}}}},"403":{"description":"Scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsRuntime"}}}},"429":{"description":"Rate limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsRuntime"}}}},"500":{"description":"Storage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsRuntime"}}}}}}},"/api/v1/behavior-candidates":{"get":{"operationId":"getBehaviorCandidates","tags":["Etapa 3 · Validation gate"],"summary":"Lista behavior_candidates de uma org (admin)","description":"Ordered por confidence desc. Default status=proposed. Aceita comma-separated statuses.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Org UUID · required · candidates são scoped por org"},"required":true,"description":"Org UUID · required · candidates são scoped por org","name":"organization_id","in":"query"},{"schema":{"type":"string","description":"Comma-separated statuses · default \"proposed\". Ex: \"proposed,approved\"","example":"proposed"},"required":false,"description":"Comma-separated statuses · default \"proposed\". Ex: \"proposed,approved\"","name":"status","in":"query"},{"schema":{"type":"string","description":"Max rows · default 100 · max 500","example":"100"},"required":false,"description":"Max rows · default 100 · max 500","name":"limit","in":"query"}],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BehaviorCandidatesListResponse"}}}},"400":{"description":"validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsBehaviorCandidates"}}}},"401":{"description":"auth","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsBehaviorCandidates"}}}},"500":{"description":"storage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsBehaviorCandidates"}}}}}}},"/api/v1/behavior-candidates/{id}/approve":{"post":{"operationId":"postBehaviorCandidatesByIdApprove","tags":["Etapa 3 · Validation gate"],"summary":"Aprova behavior_candidate + promove pra behaviors (admin)","description":"Body opcional. Se canonical já tem behavior ativo na org, retorna 409 sem promover (supersede=false) OU nova versão + deprecate (supersede=true). Edges materializadas em behavior_edges (forward + retro).","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"behavior_candidate UUID"},"required":true,"description":"behavior_candidate UUID","name":"id","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BehaviorCandidateApproveBody"}}}},"responses":{"200":{"description":"promoted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BehaviorCandidateApproveResponse"}}}},"400":{"description":"validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsBehaviorCandidates"}}}},"401":{"description":"auth","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsBehaviorCandidates"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsBehaviorCandidates"}}}},"409":{"description":"behavior_key collision · supersede=true required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BehaviorCandidateApproveConflict"}}}},"500":{"description":"storage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsBehaviorCandidates"}}}}}}},"/api/v1/behavior-candidates/{id}/reject":{"post":{"operationId":"postBehaviorCandidatesByIdReject","description":"Idempotente: rejeitar um candidato já rejeitado responde 200 sem efeito. Candidato rejeitado não volta pro pool de sugestões nem vira behavior.","tags":["Etapa 3 · Validation gate"],"summary":"Marca behavior_candidate como rejected (admin, idempotent)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"behavior_candidate UUID"},"required":true,"description":"behavior_candidate UUID","name":"id","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BehaviorCandidateRejectBody"}}}},"responses":{"200":{"description":"rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BehaviorCandidateRejectResponse"}}}},"400":{"description":"validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsBehaviorCandidates"}}}},"401":{"description":"auth","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsBehaviorCandidates"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsBehaviorCandidates"}}}},"409":{"description":"already approved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsBehaviorCandidates"}}}},"500":{"description":"storage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsBehaviorCandidates"}}}}}}},"/api/v1/evidence/{kind}/{id}":{"get":{"operationId":"getEvidenceByKindById","tags":["Evidence"],"summary":"Evidence rows de um signal, insight ou opportunity","description":"Toda resposta AI cita evidence_ref — este endpoint resolve as refs em rows completas (kind + payload + created_at). União de evidence_ref do target + rows bidirectionais.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["signal","insight","opportunity"],"description":"Target kind · signal | insight | opportunity"},"required":true,"description":"Target kind · signal | insight | opportunity","name":"kind","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Target UUID (org-scoped)"},"required":true,"description":"Target UUID (org-scoped)","name":"id","in":"path"}],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvidenceResponse"}}}},"401":{"description":"auth","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsEvidence"}}}},"403":{"description":"scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsEvidence"}}}},"404":{"description":"target not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsEvidence"}}}},"429":{"description":"rate limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsEvidence"}}}},"500":{"description":"storage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsEvidence"}}}}}}},"/api/v1/opportunities":{"get":{"operationId":"getOpportunities","tags":["Intelligence"],"summary":"Lista oportunidades da organização da chave","description":"Ordenadas da mais recente pra mais antiga. `evidence_ref` resolve em GET /v1/evidence/opportunity/{id}. Score interno (confiança, materialidade, prioridade) não é exposto.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Filtra por status · vírgula separa vários"},"required":false,"description":"Filtra por status · vírgula separa vários","name":"status","in":"query"},{"schema":{"type":"string","description":"ISO 8601 · só o que nasceu a partir daqui"},"required":false,"description":"ISO 8601 · só o que nasceu a partir daqui","name":"since","in":"query"},{"schema":{"type":"string","description":"1..200 · default 50"},"required":false,"description":"1..200 · default 50","name":"limit","in":"query"},{"schema":{"type":"string","description":"next_cursor da página anterior"},"required":false,"description":"next_cursor da página anterior","name":"cursor","in":"query"}],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpportunitiesListResponse"}}}},"400":{"description":"cursor inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsIntelligence"}}}},"401":{"description":"auth","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsIntelligence"}}}},"403":{"description":"scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsIntelligence"}}}},"429":{"description":"rate limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsIntelligence"}}}},"500":{"description":"storage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsIntelligence"}}}}}}},"/api/v1/opportunities/{id}":{"get":{"operationId":"getOpportunitiesById","description":"Mesma forma da lista, para um id só. `evidence_ref` resolve em GET /v1/evidence/opportunity/{id}. Responde 404 se a oportunidade não for da organização da chave.","tags":["Intelligence"],"summary":"Uma oportunidade pelo id","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpportunityResponse"}}}},"401":{"description":"auth","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsIntelligence"}}}},"403":{"description":"scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsIntelligence"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsIntelligence"}}}},"500":{"description":"storage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsIntelligence"}}}}}}},"/api/v1/signals":{"get":{"operationId":"getSignals","tags":["Detection"],"summary":"Lista sinais de detecção da organização da chave","description":"Sinal é mudança e expira (`expires_at`). `advisory: true` informa e nunca vira oportunidade. Default traz só os ativos.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Filtra por status · vírgula separa vários"},"required":false,"description":"Filtra por status · vírgula separa vários","name":"status","in":"query"},{"schema":{"type":"string","description":"ISO 8601 · só o que nasceu a partir daqui"},"required":false,"description":"ISO 8601 · só o que nasceu a partir daqui","name":"since","in":"query"},{"schema":{"type":"string","description":"1..200 · default 50"},"required":false,"description":"1..200 · default 50","name":"limit","in":"query"},{"schema":{"type":"string","description":"next_cursor da página anterior"},"required":false,"description":"next_cursor da página anterior","name":"cursor","in":"query"},{"schema":{"type":"string","description":"positive | negative | neutral · vírgula separa"},"required":false,"description":"positive | negative | neutral · vírgula separa","name":"type","in":"query"},{"schema":{"type":"string","description":"low | medium | high | critical · vírgula separa"},"required":false,"description":"low | medium | high | critical · vírgula separa","name":"severity","in":"query"}],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignalsListResponse"}}}},"400":{"description":"cursor inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsIntelligence"}}}},"401":{"description":"auth","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsIntelligence"}}}},"403":{"description":"scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsIntelligence"}}}},"429":{"description":"rate limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsIntelligence"}}}},"500":{"description":"storage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsIntelligence"}}}}}}},"/api/v1/metric-compositions":{"get":{"operationId":"getMetricCompositions","description":"Métrica composta é definida pelo usuário sobre behaviors — ativação, adoção, aha e time-to-value só existem depois de compostas.","tags":["Etapa 4 · Metrics Engine"],"summary":"Lista metric compositions de uma org (admin)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Org UUID · compositions são scoped por org"},"required":true,"description":"Org UUID · compositions são scoped por org","name":"organization_id","in":"query"},{"schema":{"type":"string","description":"\"true\" inclui versões deprecadas · default só ativas"},"required":false,"description":"\"true\" inclui versões deprecadas · default só ativas","name":"include_deprecated","in":"query"}],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricCompositionsListResponse"}}}},"400":{"description":"validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsMetricCompositions"}}}},"401":{"description":"auth","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsMetricCompositions"}}}},"500":{"description":"storage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsMetricCompositions"}}}}}},"post":{"operationId":"postMetricCompositions","tags":["Etapa 4 · Metrics Engine"],"summary":"Cria/versiona metric composition (admin)","description":"Depreca a composição ativa anterior de (org, metric) se existir e insere nova com version+1. As definitions precisam existir na org (qualquer versão — a série é por nome).","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricCompositionCreateBody"}}}},"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricCompositionCreateResponse"}}}},"400":{"description":"validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsMetricCompositions"}}}},"401":{"description":"auth","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsMetricCompositions"}}}},"404":{"description":"definition not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsMetricCompositions"}}}},"500":{"description":"storage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsMetricCompositions"}}}}}}},"/api/v1/cohorts":{"get":{"operationId":"getCohorts","description":"Cohort é população + recorte temporal + comportamento. A organização vem da chave, nunca do parâmetro.","tags":["Etapa 4 · Metrics Engine"],"summary":"Lista cohorts de uma org (admin)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"organization_id","in":"query"},{"schema":{"type":"string","description":"\"true\" inclui superseded/archived · default só ativos"},"required":false,"description":"\"true\" inclui superseded/archived · default só ativos","name":"include_inactive","in":"query"}],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CohortsListResponse"}}}},"400":{"description":"validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsCohorts"}}}},"401":{"description":"auth","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsCohorts"}}}},"500":{"description":"storage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsCohorts"}}}}}},"post":{"operationId":"postCohorts","tags":["Etapa 4 · Metrics Engine"],"summary":"Cria/versiona cohort (admin)","description":"Supersede a versão ativa anterior de (org, nome) e insere version+1. A série de métrica referencia o nome, então refinar o recorte preserva o histórico.","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CohortCreateBody"}}}},"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CohortCreateResponse"}}}},"400":{"description":"validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsCohorts"}}}},"401":{"description":"auth","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsCohorts"}}}},"404":{"description":"org not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsCohorts"}}}},"500":{"description":"storage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsCohorts"}}}}}}},"/api/v1/cohorts/preview":{"post":{"operationId":"postCohortsPreview","tags":["Etapa 4 · Metrics Engine"],"summary":"Resolve a definição sem persistir (admin)","description":"Mesmo resolver do tick de métricas — o que o preview mostra é o que vai ser medido.","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CohortPreviewBody"}}}},"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CohortPreviewResponse"}}}},"400":{"description":"validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsCohorts"}}}},"401":{"description":"auth","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsCohorts"}}}},"404":{"description":"org not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsCohorts"}}}},"500":{"description":"storage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsCohorts"}}}}}}},"/api/v1/state-profiles":{"get":{"operationId":"getStateProfiles","description":"Profile define as condições e os limiares que promovem uma conta de um estado comportamental para outro.","tags":["Etapa 5 · Detection"],"summary":"Lista state profiles de uma org (admin)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"organization_id","in":"query"},{"schema":{"type":"string"},"required":false,"name":"include_inactive","in":"query"}],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StateProfilesListResponse"}}}},"400":{"description":"validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsStateProfiles"}}}},"401":{"description":"auth","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsStateProfiles"}}}},"500":{"description":"storage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsStateProfiles"}}}}}},"post":{"operationId":"postStateProfiles","tags":["Etapa 5 · Detection"],"summary":"Cria/versiona state profile (admin)","description":"Supersede a versão ativa anterior de (org, nome) e insere version+1, numa transação. Definição idêntica é idempotente. A versão fica congelada em cada transição de estado que ela causar.","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StateProfileCreateBody"}}}},"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StateProfileCreateResponse"}}}},"400":{"description":"validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsStateProfiles"}}}},"401":{"description":"auth","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsStateProfiles"}}}},"404":{"description":"org not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsStateProfiles"}}}},"500":{"description":"storage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsStateProfiles"}}}}}}},"/api/v1/instrumentation/plan":{"post":{"operationId":"postInstrumentationPlan","tags":["Instrumentation"],"summary":"Propõe onde instrumentar eventos no código do cliente","description":"Recebe trechos do repositório e devolve eventos propostos com arquivo, âncora literal e snippet. Não escreve nada: quem aplica o patch é o CLI, depois de o usuário aprovar o diff.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstrumentationPlanInput"}}}},"responses":{"200":{"description":"Plano de instrumentação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstrumentationPlan"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsInstrumentation"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsInstrumentation"}}}},"403":{"description":"Key pública não pode enviar código-fonte","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsInstrumentation"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsInstrumentation"}}}},"502":{"description":"Falha ao planejar com o modelo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsInstrumentation"}}}}}}},"/api/v1/consumption":{"get":{"operationId":"getConsumption","description":"Devolve o consumo do ciclo corrente contra o teto do plano: usuários rastreados, eventos ingeridos e tokens de IA. Passe `by_account` para quebrar por conta.","tags":["Etapa 4 · Metrics Engine"],"summary":"Consumo do produto — plano, ingestão e, opcionalmente, por conta","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["workspace","account"],"description":"workspace (default) = agregado · account = drill-down por cliente"},"required":false,"description":"workspace (default) = agregado · account = drill-down por cliente","name":"scope","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":90},"required":false,"name":"window_days","in":"query"}],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsumptionResponse"}}}},"401":{"description":"auth","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsConsumption"}}}},"429":{"description":"rate limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsConsumption"}}}},"500":{"description":"storage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsConsumption"}}}}}}}},"webhooks":{}}