{"components":{"headers":{"RateLimitLimit":{"description":"Max requests per minute for this key's tier.","schema":{"type":"integer"}},"RateLimitRemaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}}},"parameters":{"Cursor":{"description":"Opaque pagination cursor from a previous response's `nextCursor` (or `next_cursor` for billing endpoints).","in":"query","name":"cursor","required":false,"schema":{"type":"string"}},"IdempotencyKey":{"description":"Retrying with the same key replays the original response.","in":"header","name":"Idempotency-Key","required":false,"schema":{"type":"string"}},"Limit":{"in":"query","name":"limit","required":false,"schema":{"default":50,"maximum":200,"minimum":1,"type":"integer"}},"PathId":{"in":"path","name":"id","required":true,"schema":{"type":"string"}}},"responses":{"BadRequest":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid request."},"Forbidden":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The key lacks the required scope, or the feature is not on the plan."},"NotFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Resource not found."},"NotImplemented":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"This endpoint is not yet available."},"RateLimited":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Rate limit or quota exceeded.","headers":{"Retry-After":{"description":"Seconds until the window resets.","schema":{"type":"integer"}}}},"ServiceUnavailable":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"A downstream service is temporarily unavailable."},"Unauthorized":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Missing or invalid API key."}},"schemas":{"Account":{"properties":{"email":{"type":"string"},"email_verified":{"type":"boolean"},"features":{"additionalProperties":{"type":"boolean"},"type":"object"},"id":{"type":"string"},"is_active":{"type":"boolean"},"name":{"type":"string"},"subscription_status":{"description":"Creem billing-lifecycle status for display only (e.g. a payment-failure banner) - never used to gate access. Omitted for accounts with no billing history.","type":"string"},"support":{"properties":{"channels":{"items":{"type":"string"},"type":"array"},"response_time_hours":{"type":"integer"}},"type":"object"},"tier":{"enum":["free","starter","growth","enterprise","custom_enterprise"],"type":"string"},"tier_name":{"description":"Human-readable tier label for display, e.g. \"Growth\".","type":"string"}},"type":"object"},"ApiKey":{"properties":{"allowedIps":{"description":"Enterprise-tier feature. Empty means no IP restriction.","items":{"type":"string"},"type":"array"},"createdAt":{"type":"string"},"environment":{"description":"Always \"live\" for any key created today; \"test\" only appears on keys issued before the test/live distinction was removed.","enum":["test","live"],"type":"string"},"expiresAt":{"nullable":true,"type":"string"},"id":{"type":"string"},"lastUsedAt":{"nullable":true,"type":"string"},"name":{"type":"string"},"prefix":{"description":"A non-secret display prefix of the key, e.g. \"lumen_live_sk_a1b2c3d4e5\".","type":"string"},"revokedAt":{"nullable":true,"type":"string"},"scopes":{"items":{"$ref":"#/components/schemas/Scope"},"type":"array"}},"type":"object"},"AskHistoryMessage":{"properties":{"citations":{"items":{"type":"object"},"type":"array"},"createdAt":{"format":"date-time","type":"string"},"role":{"enum":["user","assistant"],"type":"string"},"text":{"type":"string"}},"type":"object"},"AskResponse":{"properties":{"answer":{"type":"string"},"citations":{"items":{"properties":{"citedValue":{"type":"string"},"confidence":{"type":"number"},"fieldPath":{"type":"string"}},"type":"object"},"type":"array"},"fallbackUsed":{"type":"boolean"},"hasLowConfidenceCitation":{"type":"boolean"},"intentClassified":{"type":"string"},"intentConfidence":{"type":"number"},"llmUsed":{"type":"boolean"}},"type":"object"},"CreateWebhookSubscriptionRequest":{"properties":{"event_types":{"items":{"enum":["profile.resolved","profile.failed"],"type":"string"},"minItems":1,"type":"array"},"url":{"format":"uri","type":"string"}},"required":["url","event_types"],"type":"object"},"Error":{"properties":{"error":{"properties":{"code":{"example":"INSUFFICIENT_SCOPE","type":"string"},"details":{"additionalProperties":{"type":"string"},"type":"object"},"documentation_url":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"}},"type":"object"}},"type":"object"},"Invoice":{"properties":{"billed_at":{"format":"date-time","type":"string"},"created_at":{"format":"date-time","type":"string"},"currency_code":{"type":"string"},"id":{"type":"string"},"line_items":{"items":{"properties":{"description":{"type":"string"},"quantity":{"type":"integer"},"subtotal":{"type":"string"},"tax":{"type":"string"},"total":{"type":"string"}},"type":"object"},"type":"array"},"status":{"enum":["paid","past_due","canceled","pending"],"type":"string"},"total":{"description":"Smallest currency unit (e.g. cents for USD) as a string.","type":"string"}},"type":"object"},"LookupRequest":{"description":"Accepts either the gateway-native snake_case fields or the dashboard's camelCase fields - either client format works on this same endpoint. Supply an identifying field from ONE of the two groups (mixing is fine; camelCase fields simply alias their snake_case counterpart).\n","properties":{"businessName":{"description":"Dashboard format. Alias for identifier with identifier_type=name.","type":"string"},"countryHint":{"description":"Dashboard format. Alias for country_code.","type":"string"},"country_code":{"description":"Gateway-native. ISO 3166-1 alpha-2, example: KE.","type":"string"},"domain":{"description":"Dashboard format. Alias for identifier with identifier_type=domain.","type":"string"},"force_refresh":{"description":"Gateway-native. Bypasses the freshness cache and forces a new resolve.","type":"boolean"},"identifier":{"description":"Gateway-native. A business name or domain, per identifier_type.","type":"string"},"identifier_type":{"default":"auto","description":"Gateway-native.","enum":["auto","name","domain"],"type":"string"},"include_attributions":{"description":"Gateway-native. Adds per-field source info to the response.","type":"boolean"},"industry_hint":{"description":"Gateway-native. Helps disambiguate similar names.","type":"string"},"localityHint":{"description":"Dashboard format. Alias for location_hint.","type":"string"},"location_hint":{"description":"Gateway-native. City/region/state - required for federated countries (US, IN, BR, CA, AU, DE, MX, NG) when resolving by name.","type":"string"},"mode":{"default":"full","enum":["preview","full"],"type":"string"}},"type":"object"},"MetricPair":{"properties":{"limit":{"type":"integer"},"remaining":{"type":"integer"},"used":{"type":"integer"}},"type":"object"},"NotificationPreferences":{"properties":{"profileResolveFailedEmail":{"type":"boolean"},"webhookDeliveryFailedEmail":{"type":"boolean"}},"type":"object"},"PricingTier":{"description":"Self-serve tiers only. `custom_enterprise` is sales-assisted and cannot be self-selected via this API.","enum":["free","starter","growth","enterprise"],"type":"string"},"ProfileListResponse":{"properties":{"availableIndustries":{"description":"Every distinct industry value across this account's profiles - populate an `industry` filter dropdown from this.","items":{"type":"string"},"type":"array"},"hasMore":{"type":"boolean"},"items":{"items":{"$ref":"#/components/schemas/ProfileSummary"},"type":"array"},"nextCursor":{"description":"Pass as `cursor` to fetch the next page; null when there are no more.","nullable":true,"type":"string"},"totalCount":{"description":"Count of items on this page.","type":"integer"}},"type":"object"},"ProfileResponse":{"properties":{"profile":{"description":"The canonical 18-section profile document; each field carries a `{ value, metadata }` envelope.","type":"object"},"profileId":{"type":"string"}},"type":"object"},"ProfileSummary":{"properties":{"businessId":{"type":"string"},"industry":{"type":"string"},"name":{"type":"string"},"overallConfidence":{"type":"number"},"profileId":{"type":"string"},"synthesizedAt":{"format":"date-time","type":"string"},"website":{"nullable":true,"type":"string"}},"type":"object"},"ProfileVersion":{"properties":{"completeness":{"type":"number"},"confidence":{"type":"number"},"generatedAt":{"format":"date-time","type":"string"},"isLatest":{"type":"boolean"},"profileId":{"type":"string"},"version":{"type":"integer"}},"type":"object"},"Readiness":{"properties":{"details":{"additionalProperties":{"type":"string"},"example":{"postgres":"ok","redis":"ok"},"type":"object"},"service":{"type":"string"},"status":{"enum":["ready","not_ready"],"type":"string"},"version":{"type":"string"}},"type":"object"},"Scope":{"enum":["profiles:read","profiles:write","profiles:batch","monitoring:read","monitoring:write","webhooks:manage","account:read","account:admin"],"type":"string"},"Usage":{"properties":{"billing_cycle":{"properties":{"period_end":{"format":"date-time","type":"string"},"period_start":{"format":"date-time","type":"string"}},"type":"object"},"limits":{"properties":{"rate_limit_per_minute":{"type":"integer"}},"type":"object"},"tier":{"type":"string"},"usage":{"properties":{"ask_queries":{"$ref":"#/components/schemas/MetricPair"},"monitored_businesses":{"$ref":"#/components/schemas/MetricPair"},"profile_lookups":{"$ref":"#/components/schemas/MetricPair"}},"type":"object"}},"type":"object"},"WebhookSubscription":{"description":"The signing secret is never included here - only on creation.","properties":{"createdAt":{"format":"date-time","type":"string"},"enabled":{"type":"boolean"},"eventTypes":{"items":{"type":"string"},"type":"array"},"id":{"type":"string"},"url":{"type":"string"}},"type":"object"},"WebhookSubscriptionCreatedResponse":{"properties":{"secret":{"description":"The HMAC signing secret (whsec_...) - shown once, never again.","type":"string"},"subscription":{"$ref":"#/components/schemas/WebhookSubscription"}},"type":"object"}},"securitySchemes":{"bearerAuth":{"bearerFormat":"API Key","description":"Send your API key as a bearer token: `Authorization: Bearer lumen_live_sk_...`.","scheme":"bearer","type":"http"}}},"info":{"contact":{"email":"support@lumensieve.com","name":"LUMEN Support"},"description":"LUMEN resolves a real business from its public web footprint into one verified, richly-sourced profile, and lets you query and monitor it.\n\n**Authentication.** Every endpoint except `/health`, `/ready`, and the documentation routes requires an API key sent as a bearer token: `Authorization: Bearer lumen_live_sk_...`. Every key is issued live from creation - there is no separate test/sandbox key. Keys are created and revoked from the dashboard or via `/v1/account/keys`.\n\n**Scopes.** Each key carries scopes; each operation requires one (shown as `x-required-scope`). A key missing the required scope receives `403 INSUFFICIENT_SCOPE`.\n\n**Errors.** Every error response uses a single envelope (`{ \"error\": { \"code\", \"message\", \"request_id\", \"documentation_url\" } }`). Codes are stable strings safe to branch on.\n\n**Idempotency.** Mutating POSTs accept an `Idempotency-Key` header; retrying with the same key replays the original response instead of repeating the effect.\n\n**Note on availability.** `/v1/profiles/batch*` and the monitor-scoped webhook delivery endpoints (`/v1/webhooks/deliveries*`, `/v1/webhooks/test`, `/v1/webhooks/dead-letter*`) are not yet implemented and return `501 NOT_IMPLEMENTED` in production; they are documented here for the forthcoming contract. Account-level webhook **subscriptions** (`/v1/webhooks/subscriptions`) are fully implemented today and unrelated to that stub - see the Webhooks tag below.\n","title":"LUMEN API","version":"1.0.0"},"openapi":"3.0.3","paths":{"/health":{"get":{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"service":{"example":"api-gateway","type":"string"},"status":{"example":"alive","type":"string"},"version":{"type":"string"}},"type":"object"}}},"description":"Process is alive."}},"security":[],"summary":"Liveness probe","tags":["System"]}},"/ready":{"get":{"description":"Returns 200 only when the required infrastructure (Postgres when persistence is enabled, Redis when rate limiting is enabled) is reachable; otherwise 503 with per-dependency detail.\n","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Readiness"}}},"description":"Ready to serve traffic."},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Readiness"}}},"description":"A required dependency is unreachable."}},"security":[],"summary":"Readiness probe","tags":["System"]}},"/v1/account":{"delete":{"description":"Cancels any active Creem subscription immediately, then deletes the account and its data. Requires typing the account's exact current name as a confirmation gate - irreversible.\n","requestBody":{"content":{"application/json":{"schema":{"properties":{"confirmName":{"description":"Must exactly match the account's current name.","type":"string"}},"required":["confirmName"],"type":"object"}}},"required":true},"responses":{"200":{"description":"Deleted."},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"Permanently delete the account","tags":["Usage \u0026 Account"],"x-required-scope":"account:admin"},"get":{"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}},"description":"The account."}},"summary":"Get the caller's account","tags":["Usage \u0026 Account"],"x-required-scope":"account:read"},"patch":{"description":"Renames the organization/company name shown on invoices, support tickets, and the dashboard.","requestBody":{"content":{"application/json":{"schema":{"properties":{"name":{"maxLength":100,"type":"string"}},"required":["name"],"type":"object"}}},"required":true},"responses":{"200":{"description":"Renamed."},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"Rename the account","tags":["Usage \u0026 Account"],"x-required-scope":"account:admin"}},"/v1/account/contact-support":{"post":{"description":"Emails the account's message to LUMEN's support inbox (support@lumensieve.com) - there is no in-app ticket queue, so this is the entire delivery mechanism. Rate-limited per account.\n","requestBody":{"content":{"application/json":{"schema":{"properties":{"message":{"maxLength":5000,"type":"string"}},"required":["message"],"type":"object"}}},"required":true},"responses":{"200":{"description":"Sent."},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Send a message to LUMEN support","tags":["Usage \u0026 Account"],"x-required-scope":"account:read"}},"/v1/account/keys":{"get":{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"apiKeys":{"items":{"$ref":"#/components/schemas/ApiKey"},"type":"array"}},"type":"object"}}},"description":"The account's API keys (never the raw secret)."}},"summary":"List API keys","tags":["Usage \u0026 Account"],"x-required-scope":"account:read"},"post":{"description":"The raw key is returned once and never again. Every key is issued \"live\" from creation - the `environment` field is accepted for backward compatibility but always overridden to `live` server-side; there is no way to mint a test/sandbox key.\n","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"environment":{"description":"Accepted but ignored - every key is always \"live\".","enum":["live"],"type":"string"},"expires_at_unix":{"description":"Unix timestamp the key expires at. Omit for a key that never expires.","type":"integer"},"name":{"type":"string"},"scopes":{"items":{"$ref":"#/components/schemas/Scope"},"type":"array"}},"required":["name"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"properties":{"apiKey":{"$ref":"#/components/schemas/ApiKey"},"rawKey":{"description":"Shown once; store it securely.","type":"string"}},"type":"object"}}},"description":"The created key plus its one-time raw secret."},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"}},"summary":"Create an API key","tags":["Usage \u0026 Account"],"x-required-scope":"account:admin"}},"/v1/account/keys/{id}":{"delete":{"parameters":[{"$ref":"#/components/parameters/PathId"}],"responses":{"200":{"description":"Revoked."},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"Revoke an API key","tags":["Usage \u0026 Account"],"x-required-scope":"account:admin"}},"/v1/account/keys/{id}/allowed-ips":{"patch":{"description":"Enterprise-tier feature (`ip_allowlist`). A wholesale replacement of the key's allowlist - an empty array clears the restriction. Each entry must be a valid IPv4/IPv6 address or CIDR range.\n","parameters":[{"$ref":"#/components/parameters/PathId"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"allowedIps":{"example":["203.0.113.5","203.0.113.0/24"],"items":{"type":"string"},"type":"array"}},"required":["allowedIps"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"apiKey":{"$ref":"#/components/schemas/ApiKey"}},"type":"object"}}},"description":"Updated."},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The account's plan does not include IP allowlisting, or the key lacks the required scope."}},"summary":"Restrict an API key to specific source IPs","tags":["Usage \u0026 Account"],"x-required-scope":"account:admin"}},"/v1/account/notifications":{"get":{"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationPreferences"}}},"description":"The account's opt-in email toggles."}},"summary":"Get notification preferences","tags":["Usage \u0026 Account"],"x-required-scope":"account:read"},"patch":{"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationPreferences"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationPreferences"}}},"description":"Updated."}},"summary":"Update notification preferences","tags":["Usage \u0026 Account"],"x-required-scope":"account:admin"}},"/v1/account/profile":{"patch":{"description":"Renames the individual signed-in user (the dashboard's \"Profile\" display name) - distinct from `PATCH /v1/account`, which renames the organization. Only reachable from a dashboard session; a raw API key has no associated login user and receives 403.\n","requestBody":{"content":{"application/json":{"schema":{"properties":{"name":{"maxLength":100,"type":"string"}},"required":["name"],"type":"object"}}},"required":true},"responses":{"200":{"description":"Renamed."},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"description":"Not a dashboard session (raw API keys cannot rename a user)."}},"summary":"Rename the signed-in user","tags":["Usage \u0026 Account"],"x-required-scope":"account:admin"}},"/v1/billing/checkout-token":{"get":{"description":"Mints a short-lived, signed token binding a Creem Checkout session to this account, so a new subscription is correctly attributed server-side (never trusting a client-supplied account ID). Acquires a per-account lock so a second checkout cannot start concurrently; release it via `/v1/billing/checkout-token/release` once the checkout overlay closes.\n","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"token":{"type":"string"}},"type":"object"}}},"description":"The checkout token."},"400":{"description":"A checkout is already in progress for this account."}},"summary":"Mint a checkout attribution token","tags":["Billing"],"x-required-scope":"account:read"}},"/v1/billing/checkout-token/release":{"post":{"description":"Safe to call even when no lock is held. Call unconditionally once the customer returns from Creem's hosted checkout, regardless of the outcome.","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"released":{"type":"boolean"}},"type":"object"}}},"description":"Released."}},"summary":"Release the checkout lock","tags":["Billing"],"x-required-scope":"account:read"}},"/v1/billing/invoices":{"get":{"parameters":[{"in":"query","name":"status","required":false,"schema":{"enum":["paid","past_due","canceled","pending"],"type":"string"}},{"description":"RFC 3339 inclusive lower bound on `billed_at`.","in":"query","name":"from","required":false,"schema":{"format":"date-time","type":"string"}},{"description":"RFC 3339 inclusive upper bound on `billed_at`.","in":"query","name":"to","required":false,"schema":{"format":"date-time","type":"string"}},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"has_more":{"type":"boolean"},"invoices":{"items":{"$ref":"#/components/schemas/Invoice"},"type":"array"},"next_cursor":{"nullable":true,"type":"string"}},"type":"object"}}},"description":"A page of invoices."},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"List billing invoices","tags":["Billing"],"x-required-scope":"account:read"}},"/v1/billing/invoices/{id}/pdf":{"get":{"description":"Returns Creem's signed PDF URL (short-lived, ~1 hour) rather than proxying the bytes - redirect the browser to it directly.\n","parameters":[{"$ref":"#/components/parameters/PathId"}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"url":{"type":"string"}},"type":"object"}}},"description":"The signed PDF URL."},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"Get an invoice's PDF URL","tags":["Billing"],"x-required-scope":"account:read"}},"/v1/billing/portal":{"post":{"description":"Returns a short-lived Creem customer portal link. Redirect the customer to `overview_url` - all subscription/payment-method changes made there happen on Creem's own hosted pages; Creem's webhook syncs the result back to LUMEN. `cancel_url` and `update_payment_method_url` are part of the schema but are omitted in practice: Creem's portal is a single page rather than separate deep links.\n","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"cancel_url":{"type":"string"},"overview_url":{"type":"string"},"update_payment_method_url":{"type":"string"}},"type":"object"}}},"description":"Portal links."},"400":{"description":"No billing account yet - subscribe to a paid plan first."},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"summary":"Create a Creem customer portal session","tags":["Billing"],"x-required-scope":"account:read"}},"/v1/billing/subscription":{"patch":{"description":"Moves the account's EXISTING Creem subscription to a different tier in place (proration), instead of routing through Checkout again - Checkout is only for a brand-new subscription. Downgrading to `free` cancels the subscription at period end instead of an immediate Creem price change.\n","requestBody":{"content":{"application/json":{"schema":{"properties":{"tier":{"$ref":"#/components/schemas/PricingTier"}},"required":["tier"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"effective_at":{"description":"Only set when scheduled.","format":"date-time","type":"string"},"scheduled":{"description":"true: a downgrade - stays on the current tier until effective_at. false: an upgrade - applied and charged immediately.","type":"boolean"},"tier":{"type":"string"}},"type":"object"}}},"description":"Changed (or scheduled, for a downgrade)."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"No active subscription to change (use Checkout instead), Custom Enterprise is sales-assisted, or a change is already pending."}},"summary":"Change subscription tier","tags":["Billing"],"x-required-scope":"account:admin"}},"/v1/billing/subscription/cancel":{"post":{"requestBody":{"content":{"application/json":{"schema":{"properties":{"at_period_end":{"default":true,"description":"true (default) keeps access until the current billing period ends; false cancels immediately.","type":"boolean"}},"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"canceled":{"type":"boolean"}},"type":"object"}}},"description":"Canceled."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"A change is already pending on this subscription."}},"summary":"Cancel the subscription","tags":["Billing"],"x-required-scope":"account:admin"}},"/v1/billing/subscription/preview":{"post":{"description":"Shows what changing to the requested tier would actually do before committing to it: the prorated amount due now for an upgrade, or the scheduled effective date for a downgrade. Creem publishes no preview API, so the upgrade figure is LUMEN's own linear estimate from the tier prices and the days left in the period - the charge Creem actually applies can differ by a small rounding amount.\n","requestBody":{"content":{"application/json":{"schema":{"properties":{"tier":{"$ref":"#/components/schemas/PricingTier"}},"required":["tier"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"amount_cents":{"description":"Only meaningful when is_upgrade is true.","type":"integer"},"currency_code":{"type":"string"},"effective_at":{"format":"date-time","type":"string"},"is_upgrade":{"type":"boolean"}},"type":"object"}}},"description":"The preview."}},"summary":"Preview a tier change","tags":["Billing"],"x-required-scope":"account:read"}},"/v1/monitoring/monitors":{"get":{"parameters":[{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"A page of monitors."}},"summary":"List monitors","tags":["Monitoring"],"x-required-scope":"monitoring:read"},"post":{"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"business_identifier":{"type":"string"},"check_interval_seconds":{"type":"integer"},"event_types":{"items":{"type":"string"},"type":"array"},"webhook_url":{"type":"string"}},"type":"object"}}},"required":true},"responses":{"201":{"description":"Monitor created; signing secret returned once."},"403":{"$ref":"#/components/responses/Forbidden"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"summary":"Create a monitor","tags":["Monitoring"],"x-required-scope":"monitoring:write"}},"/v1/monitoring/monitors/{id}":{"delete":{"parameters":[{"$ref":"#/components/parameters/PathId"}],"responses":{"204":{"description":"Deleted."}},"summary":"Delete a monitor","tags":["Monitoring"],"x-required-scope":"monitoring:write"},"get":{"parameters":[{"$ref":"#/components/parameters/PathId"}],"responses":{"200":{"description":"The monitor."},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"Get a monitor","tags":["Monitoring"],"x-required-scope":"monitoring:read"},"patch":{"parameters":[{"$ref":"#/components/parameters/PathId"}],"responses":{"200":{"description":"Updated."}},"summary":"Update a monitor","tags":["Monitoring"],"x-required-scope":"monitoring:write"}},"/v1/monitoring/monitors/{id}/changes":{"get":{"parameters":[{"$ref":"#/components/parameters/PathId"}],"responses":{"200":{"description":"A page of change events."}},"summary":"List detected changes","tags":["Monitoring"],"x-required-scope":"monitoring:read"}},"/v1/monitoring/monitors/{id}/check":{"post":{"parameters":[{"$ref":"#/components/parameters/PathId"}],"responses":{"202":{"description":"Check queued."}},"summary":"Trigger an out-of-band check","tags":["Monitoring"],"x-required-scope":"monitoring:write"}},"/v1/monitoring/monitors/{id}/pause":{"post":{"parameters":[{"$ref":"#/components/parameters/PathId"}],"responses":{"200":{"description":"Paused."}},"summary":"Pause a monitor","tags":["Monitoring"],"x-required-scope":"monitoring:write"}},"/v1/monitoring/monitors/{id}/resume":{"post":{"parameters":[{"$ref":"#/components/parameters/PathId"}],"responses":{"200":{"description":"Active."}},"summary":"Resume a monitor","tags":["Monitoring"],"x-required-scope":"monitoring:write"}},"/v1/profiles":{"get":{"description":"Lists the latest profile for each distinct business the account has looked up, most recent first. Keyset (cursor) pagination.\n","parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"},{"description":"Free-text search over business name.","in":"query","name":"q","required":false,"schema":{"type":"string"}},{"description":"Filter to one industry (see the response's `availableIndustries`).","in":"query","name":"industry","required":false,"schema":{"type":"string"}},{"description":"Sort order. Anything else falls back to `recent`.","in":"query","name":"sort","required":false,"schema":{"default":"recent","enum":["recent","completeness","name"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileListResponse"}}},"description":"A page of profile summaries.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"List recent profiles","tags":["Profiles"],"x-required-scope":"profiles:read"}},"/v1/profiles/batch":{"post":{"description":"Returns 501 until the batch pipeline ships.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"identifiers":{"items":{"type":"string"},"type":"array"},"webhook_url":{"type":"string"}},"type":"object"}}}},"responses":{"501":{"$ref":"#/components/responses/NotImplemented"}},"summary":"Submit a batch of lookups (not yet available)","tags":["Profiles"],"x-required-scope":"profiles:batch"}},"/v1/profiles/batch/{id}":{"get":{"parameters":[{"$ref":"#/components/parameters/PathId"}],"responses":{"501":{"$ref":"#/components/responses/NotImplemented"}},"summary":"Get batch status (not yet available)","tags":["Profiles"],"x-required-scope":"profiles:batch"}},"/v1/profiles/lookup":{"post":{"description":"Resolves a business into the full profile document - by name + country, or by domain alone (identifier_type=domain, or the dashboard-format `domain` field) when the caller already knows the business's website. A domain-only request deep-crawls that domain first to derive the business's real name, fingerprints, and country directly from the site - no country_code/location_hint required, even for federated countries. `mode=preview` returns a fast partial; `mode=full` runs the complete pipeline. Idempotent via `Idempotency-Key`.\n","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LookupRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileResponse"}}},"description":"The resolved profile."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"summary":"Resolve (or fetch) a business profile","tags":["Profiles"],"x-required-scope":"profiles:write"}},"/v1/profiles/lookup/stream":{"post":{"description":"Same as `/v1/profiles/lookup` but streams `text/event-stream` progress events (stage_start, stage_complete, partial_profile, complete).\n","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LookupRequest"}}},"required":true},"responses":{"200":{"content":{"text/event-stream":{"schema":{"type":"string"}}},"description":"An event stream of pipeline progress."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"summary":"Resolve a profile with streaming progress (SSE)","tags":["Profiles"],"x-required-scope":"profiles:write"}},"/v1/profiles/{id}":{"get":{"description":"`id` may be a profile UUID or a business UUID (resolves to the latest profile).","parameters":[{"$ref":"#/components/parameters/PathId"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileResponse"}}},"description":"The profile document."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"Get a stored profile","tags":["Profiles"],"x-required-scope":"profiles:read"}},"/v1/profiles/{id}/ask":{"post":{"description":"Grounded answer with citations, or an honest refusal when the profile lacks the data.","parameters":[{"$ref":"#/components/parameters/PathId"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"conversation_history":{"items":{"type":"string"},"type":"array"},"question":{"maxLength":1000,"type":"string"}},"required":["question"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AskResponse"}}},"description":"The grounded answer."},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"}},"summary":"Ask a question about a profile","tags":["Ask Lumen Sieve"],"x-required-scope":"profiles:read"}},"/v1/profiles/{id}/ask/history":{"get":{"parameters":[{"$ref":"#/components/parameters/PathId"}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"messages":{"items":{"$ref":"#/components/schemas/AskHistoryMessage"},"type":"array"}},"type":"object"}}},"description":"The saved conversation, oldest first."}},"summary":"Get saved Ask Lumen Sieve conversation","tags":["Ask Lumen Sieve"],"x-required-scope":"profiles:read"}},"/v1/profiles/{id}/attribution/{fieldPath}":{"get":{"description":"Returns 501 in production until wired to the attribution graph.","parameters":[{"$ref":"#/components/parameters/PathId"},{"in":"path","name":"fieldPath","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Attribution (development stub)."},"501":{"$ref":"#/components/responses/NotImplemented"}},"summary":"Per-field source attribution (not yet available)","tags":["Profiles"],"x-required-scope":"profiles:read"}},"/v1/profiles/{id}/corrections":{"post":{"parameters":[{"$ref":"#/components/parameters/PathId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"correct_value":{},"explanation":{"type":"string"},"field_path":{"example":"contact.phone","type":"string"}},"required":["field_path","correct_value"],"type":"object"}}},"required":true},"responses":{"202":{"description":"Correction accepted for review."},"400":{"$ref":"#/components/responses/BadRequest"}},"summary":"Submit a field correction","tags":["Profiles"],"x-required-scope":"profiles:write"}},"/v1/profiles/{id}/history":{"get":{"description":"Every stored version of a business's profile, newest first.","parameters":[{"$ref":"#/components/parameters/PathId"}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"versions":{"items":{"$ref":"#/components/schemas/ProfileVersion"},"type":"array"}},"type":"object"}}},"description":"Version history."},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"List a profile's version history","tags":["Profiles"],"x-required-scope":"profiles:read"}},"/v1/profiles/{id}/refresh":{"post":{"parameters":[{"$ref":"#/components/parameters/PathId"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileResponse"}}},"description":"The refreshed profile."},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Force a fresh re-resolve","tags":["Profiles"],"x-required-scope":"profiles:write"}},"/v1/usage":{"get":{"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"}}},"description":"Usage and tier limits."}},"summary":"Current usage and limits","tags":["Usage \u0026 Account"],"x-required-scope":"account:read"}},"/v1/usage/summary":{"get":{"responses":{"200":{"description":"Usage summary."}},"summary":"Usage summary for the current period","tags":["Usage \u0026 Account"],"x-required-scope":"account:read"}},"/v1/usage/timeseries":{"get":{"responses":{"200":{"description":"Usage points."}},"summary":"Daily usage time series","tags":["Usage \u0026 Account"],"x-required-scope":"account:read"}},"/v1/webhooks/deliveries":{"get":{"description":"MONITOR-scoped delivery history (not the account-level subscriptions above). Not yet wired to the webhook-service in production - returns 501.\n","responses":{"200":{"description":"Deliveries (development stub)."},"501":{"$ref":"#/components/responses/NotImplemented"}},"summary":"List webhook deliveries (not yet available)","tags":["Webhooks"],"x-required-scope":"webhooks:manage"}},"/v1/webhooks/subscriptions":{"get":{"description":"Fully implemented. The signing secret is never included.","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"subscriptions":{"items":{"$ref":"#/components/schemas/WebhookSubscription"},"type":"array"}},"type":"object"}}},"description":"This account's webhook subscriptions."},"401":{"$ref":"#/components/responses/Unauthorized"}},"summary":"List account-level webhook subscriptions","tags":["Webhooks"],"x-required-scope":"webhooks:manage"},"post":{"description":"Fully implemented. Registers a URL to receive `profile.resolved` and/or `profile.failed` events fired by any async `/v1/profiles/lookup` on this account (no monitor required). The signing secret is returned once, at creation, and never echoed back by list/delete.\n","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookSubscriptionRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscriptionCreatedResponse"}}},"description":"Subscription created; signing secret returned once."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}},"summary":"Create an account-level webhook subscription","tags":["Webhooks"],"x-required-scope":"webhooks:manage"}},"/v1/webhooks/subscriptions/{id}":{"delete":{"description":"Fully implemented.","parameters":[{"$ref":"#/components/parameters/PathId"}],"responses":{"200":{"description":"Deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"Delete an account-level webhook subscription","tags":["Webhooks"],"x-required-scope":"webhooks:manage"}},"/v1/webhooks/test":{"post":{"responses":{"200":{"description":"Test result (development stub)."},"501":{"$ref":"#/components/responses/NotImplemented"}},"summary":"Test a webhook endpoint (not yet available)","tags":["Webhooks"],"x-required-scope":"webhooks:manage"}}},"security":[{"bearerAuth":[]}],"servers":[{"description":"Production","url":"https://api.lumensieve.com"},{"description":"Local development","url":"http://localhost:8080"}],"tags":[{"description":"Resolve, retrieve, refresh, and query business profiles.","name":"Profiles"},{"description":"Natural-language questions grounded on a profile.","name":"Ask Lumen Sieve"},{"description":"Watch businesses for changes and deliver webhooks.","name":"Monitoring"},{"description":"Account-level webhook subscriptions (real, implemented) plus monitor-scoped delivery inspection (not yet available - see the per-operation `Not yet available` notes).\n","name":"Webhooks"},{"description":"Account details, usage, profile/notification settings, and API keys.","name":"Usage \u0026 Account"},{"description":"Subscription tier changes, cancellation, invoices, and the Creem customer portal.","name":"Billing"},{"description":"Health and readiness probes.","name":"System"}]}