{"components":{"schemas":{"Active":{"additionalProperties":false,"properties":{"active":{"type":"boolean"}},"required":["active"],"type":"object"},"AgentLink":{"additionalProperties":false,"properties":{"agent_name":{"description":"Shown to the person approving access and used as the API token name. 1 to 80 characters, no line breaks.","maxLength":80,"minLength":1,"type":"string"}},"required":["agent_name"],"type":"object"},"AgentLinkPoll":{"additionalProperties":false,"properties":{"poll_token":{"pattern":"^slp_[0-9a-f]{64}$","type":"string"}},"required":["poll_token"],"type":"object"},"CampaignBatch":{"additionalProperties":false,"properties":{"goals":{"items":{"enum":["get_recommended"]},"maxItems":1,"minItems":1,"type":"array","uniqueItems":true},"options":{"$ref":"#/components/schemas/CampaignSetupOptions"},"request_id":{"type":"string"}},"required":["request_id","goals"],"type":"object"},"CampaignBrief":{"additionalProperties":false,"properties":{"audience":{"maxLength":500,"minLength":1,"type":"string"},"country":{"pattern":"^[A-Z]{2}$","type":"string"},"language":{"default":"unknown","description":"BCP 47 language tag, e.g. en, fr-BE, pl or sr-Latn; unknown preserves unspecified metadata.","type":"string"},"objective":{"enum":["get_recommended"]},"questions":{"items":{"$ref":"#/components/schemas/CampaignQuestion"},"maxItems":25,"type":"array"},"use_case":{"description":"Buyer need expressed as an action, e.g. reduce repeated logic.","maxLength":500,"minLength":1,"type":"string"}},"required":["objective","audience","use_case","language","country"],"type":"object"},"CampaignCreate":{"additionalProperties":false,"properties":{"brief":{"$ref":"#/components/schemas/CampaignBrief"},"engine_ids":{"items":{"type":"string"},"maxItems":20,"minItems":1,"type":"array"},"request_id":{"maxLength":150,"minLength":1,"type":"string"}},"required":["request_id","brief","engine_ids"],"type":"object"},"CampaignEngines":{"additionalProperties":false,"properties":{"engine_ids":{"items":{"type":"string"},"maxItems":20,"minItems":1,"type":"array"}},"required":["engine_ids"],"type":"object"},"CampaignPanel":{"additionalProperties":false,"properties":{"engine_ids":{"items":{"type":"string"},"type":"array"},"questions":{"items":{"$ref":"#/components/schemas/CampaignQuestion"},"maxItems":25,"type":"array"}},"required":[],"type":"object"},"CampaignQuestion":{"additionalProperties":false,"properties":{"kind":{"enum":["discovery","brand"]},"text":{"maxLength":4000,"minLength":1,"type":"string"}},"required":["text","kind"],"type":"object"},"CampaignSetupOptions":{"additionalProperties":false,"properties":{"audience":{"type":"string"},"country":{"pattern":"^[A-Za-z]{2}$","type":"string"},"engine_ids":{"items":{"type":"string"},"type":"array"},"language":{"default":"unknown","description":"BCP 47 language tag, e.g. en, fr-BE, pl or sr-Latn; unknown preserves unspecified metadata.","type":"string"},"questions":{"additionalProperties":{"items":{"$ref":"#/components/schemas/CampaignQuestion"},"type":"array"},"type":"object"},"use_case":{"type":"string"}},"required":[],"type":"object"},"CampaignSetupPlan":{"additionalProperties":false,"properties":{"goals":{"items":{"enum":["get_recommended"]},"maxItems":1,"minItems":1,"type":"array","uniqueItems":true},"options":{"$ref":"#/components/schemas/CampaignSetupOptions"}},"required":["goals"],"type":"object"},"Change":{"additionalProperties":false,"properties":{"baseline_content_sha256":{"pattern":"^[a-fA-F0-9]{64}$","type":"string"},"campaign_id":{"type":"string"},"content":{"type":"string"},"evidence_ids":{"items":{"type":"string"},"type":"array"},"expected_effect":{"type":"string"},"format":{"enum":["markdown","unified_diff"]},"language":{"default":"unknown","description":"BCP 47 language tag, e.g. en, fr-BE, pl or sr-Latn; unknown preserves unspecified metadata.","type":"string"},"question_ids":{"items":{"type":"string"},"type":"array"},"rationale":{"type":"string"},"target_url":{"format":"uri","type":"string"},"title":{"type":"string"}},"required":["campaign_id","title","target_url","format","content","baseline_content_sha256","rationale","expected_effect","question_ids","evidence_ids"],"type":"object"},"Checkout":{"additionalProperties":false,"properties":{"amount_usd":{"description":"Whole dollars, one of top_up_amounts_usd from GET /v1/billing. Required for top_up; not allowed for subscription.","type":"integer"},"kind":{"enum":["subscription","top_up"]},"plan":{"description":"Plan id from GET /v1/billing plans, for subscription only. Defaults to the cheapest plan; omit it for an account with a custom contract, which subscribes at its own Price.","type":"string"}},"required":["kind"],"type":"object"},"CitationRepair":{"additionalProperties":false,"properties":{"citations":{"items":{"type":"string"},"type":"array"},"evidence_sha256":{"pattern":"^[a-fA-F0-9]{64}$","type":"string"},"extractor":{"type":"string"}},"required":["citations","evidence_sha256","extractor"],"type":"object"},"Claim":{"additionalProperties":false,"properties":{"collection_route":{"description":"Optional. Claim only jobs whose engine uses this collection route, e.g. gemini_api.","type":"string"},"engine":{"type":"string"},"product_id":{"description":"Optional. Claim only this product's jobs, e.g. an operator calibration run.","type":"string"}},"required":["engine"],"type":"object"},"ConnectionCreate":{"additionalProperties":false,"properties":{"provider":{"enum":["cloudflare","google","bing"],"type":"string"},"request_id":{"maxLength":150,"minLength":1,"type":"string"}},"required":["provider","request_id"],"type":"object"},"ConnectionLink":{"additionalProperties":false,"properties":{"connection_id":{"type":"string"}},"required":["connection_id"],"type":"object"},"ConnectionSetup":{"additionalProperties":false,"properties":{"purposes":{"description":"Defaults to dns and search_console. A purpose with no connectable provider is rejected.","items":{"enum":["dns","search_console","traffic","publishing"],"type":"string"},"type":"array"},"request_id":{"maxLength":150,"minLength":1,"type":"string"}},"required":["request_id"],"type":"object"},"Decision":{"additionalProperties":false,"properties":{"decision":{"enum":["retain","revise","revert","wait"]},"evaluation_id":{"type":"string"},"reason":{"type":"string"}},"required":["evaluation_id","decision","reason"],"type":"object"},"Engine":{"additionalProperties":false,"properties":{"collection_route":{"default":"unknown","description":"Collection condition; part of engine identity. Official-API routes openai_api, gemini_api and perplexity_api require surface model_api, engine name openai, gemini or perplexity, and a search_mode from config/api-collectors.json. gemini_api requires country unknown.","type":"string"},"country":{"type":"string"},"name":{"type":"string"},"notes":{"type":"string"},"search_mode":{"type":"string"},"status":{"enum":["ready","unavailable"]},"surface":{"type":"string"}},"required":["name","surface","status"],"type":"object"},"EngineStatus":{"additionalProperties":false,"properties":{"notes":{"type":"string"},"status":{"enum":["ready","unavailable"]}},"required":["status"],"type":"object"},"Evaluation":{"additionalProperties":false,"properties":{"baseline_from":{"format":"date-time","type":"string"},"minimum_samples":{"description":"Uses the saved measurement plan when present; otherwise defaults to 3","maximum":10000,"minimum":3,"type":"integer"}},"required":[],"type":"object"},"Invalidation":{"additionalProperties":false,"properties":{"reason":{"maxLength":1000,"minLength":1,"type":"string"}},"required":["reason"],"type":"object"},"MeasurementPlan":{"additionalProperties":false,"properties":{"baseline_from":{"format":"date-time","type":"string"},"minimum_samples":{"default":3,"maximum":100,"minimum":3,"type":"integer"}},"required":[],"type":"object"},"MeasurementWave":{"additionalProperties":false,"properties":{"max_jobs":{"default":6,"maximum":100,"minimum":1,"type":"integer"},"request_id":{"type":"string"},"spread_seconds":{"default":3600,"maximum":86400,"minimum":0,"type":"integer"}},"required":["request_id"],"type":"object"},"Named":{"additionalProperties":false,"properties":{"name":{"type":"string"}},"required":["name"],"type":"object"},"Observation":{"additionalProperties":false,"properties":{"actual_country":{"type":"string"},"actual_language":{"default":"unknown","description":"BCP 47 language tag, e.g. en, fr-BE, pl or sr-Latn; unknown preserves unspecified metadata.","type":"string"},"actual_search_mode":{"type":"string"},"answer":{"type":["string","null"]},"citations":{"items":{"type":"string"},"type":"array"},"cost_microusd":{"description":"Supplier cost of collecting this answer in micro-dollars; null when unknown. Responses show it to operators only.","minimum":0,"type":["integer","null"]},"engine_id":{"type":"string"},"error":{"type":["string","null"]},"external_id":{"type":["string","null"]},"model":{"type":"string"},"observed_at":{"format":"date-time","type":"string"},"provenance":{"enum":["live","historical_import","synthetic"]},"question_id":{"type":"string"},"raw":{},"status":{"enum":["completed","failed"]}},"required":["question_id","engine_id","observed_at","status"],"type":"object"},"PlanChange":{"additionalProperties":false,"properties":{"plan":{"description":"Plan id from GET /v1/billing plans.","type":"string"}},"required":["plan"],"type":"object"},"Product":{"additionalProperties":false,"properties":{"audience":{"type":"string"},"description":{"type":"string"},"facts":{"items":{"type":"string"},"type":"array"},"name":{"type":"string"},"website":{"format":"uri","type":"string"}},"required":["name","website","description","audience"],"type":"object"},"Publication":{"additionalProperties":false,"properties":{"baseline_content_sha256":{"type":"string"},"published_at":{"format":"date-time","type":"string"},"revision":{"type":"string"},"settle_seconds":{"default":86400,"maximum":2592000,"minimum":0,"type":"integer"}},"required":["published_at","revision","baseline_content_sha256"],"type":"object"},"Question":{"additionalProperties":false,"properties":{"holdout":{"type":"boolean"},"kind":{"enum":["discovery","brand","diagnostic"]},"language":{"default":"unknown","description":"BCP 47 language tag, e.g. en, fr-BE, pl or sr-Latn; unknown preserves unspecified metadata.","type":"string"},"text":{"type":"string"}},"required":["text","kind"],"type":"object"},"QuestionPlan":{"additionalProperties":false,"properties":{"audiences":{"items":{"additionalProperties":false,"properties":{"basis":{"enum":["inferred_product_context","supplied_research"]},"id":{"type":"string"},"label":{"type":"string"},"need":{"type":"string"},"phrasing":{"type":"string"},"source":{"type":"string"}},"required":["id","label","need","phrasing","basis","source"],"type":"object"},"maxItems":4,"minItems":1,"type":"array"},"questions":{"items":{"additionalProperties":false,"properties":{"audience_id":{"type":"string"},"intent":{"type":"string"},"kind":{"enum":["discovery"]},"language":{"type":"string"},"text":{"type":"string"}},"required":["audience_id","intent","text","kind","language"],"type":"object"},"maxItems":25,"minItems":6,"type":"array"},"scope_notes":{"type":"string"}},"required":["audiences","questions","scope_notes"],"type":"object"},"QuestionPreparationResult":{"additionalProperties":false,"properties":{"error":{"type":"string"},"lease_token":{"type":"string"},"model":{"type":"string"},"output":{"$ref":"#/components/schemas/QuestionPlan"},"usage":{}},"required":["lease_token"],"type":"object"},"Questions":{"additionalProperties":false,"properties":{"questions":{"items":{"$ref":"#/components/schemas/Question"},"type":"array"}},"required":["questions"],"type":"object"},"Result":{"additionalProperties":false,"properties":{"lease_token":{"type":"string"},"observation":{"$ref":"#/components/schemas/Observation"}},"required":["lease_token","observation"],"type":"object"},"Sample":{"additionalProperties":false,"properties":{"engine_ids":{"items":{"type":"string"},"type":"array"},"question_ids":{"items":{"type":"string"},"type":"array"}},"required":["question_ids"],"type":"object"},"Schedule":{"additionalProperties":false,"properties":{"enabled":{"type":"boolean"},"interval_seconds":{"maximum":2592000,"minimum":60,"type":"integer"},"sample_size":{"maximum":250,"minimum":1,"type":"integer"}},"required":["interval_seconds","sample_size","enabled"],"type":"object"},"SiteCheck":{"additionalProperties":false,"properties":{"paths":{"items":{"description":"Optional path on the product website, e.g. /about; no query or fragment.","type":"string"},"maxItems":6,"type":"array"},"request_id":{"maxLength":150,"minLength":1,"type":"string"}},"required":["request_id"],"type":"object"}},"securitySchemes":{"BearerAuth":{"scheme":"bearer","type":"http"}}},"info":{"description":"Agent-first, user-isolated observation → change → remeasurement workflow. Agents use bearer tokens; an agent without an account gets one through POST /v1/agent-links and a person's one-link approval. The browser workspace calls the same handlers as the signed-in person. Customers see what they were charged (charged_microusd); supplier-cost fields appear only in responses to operators.","title":"Search Optimization API","version":"0.3.0"},"openapi":"3.1.0","paths":{"/health":{"get":{"operationId":"health","responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"security":[],"summary":"Process health; no authentication needed"}},"/openapi.json":{"get":{"operationId":"openapi","responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"security":[],"summary":"Agent-readable API contract"}},"/stripe/webhook":{"post":{"operationId":"stripeWebhook","parameters":[{"in":"header","name":"Stripe-Signature","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"description":"Stripe Event object, verified byte for byte","type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Missing, invalid or stale signature, or a malformed event"},"409":{"description":"The invoice belongs to a subscription not recorded yet; nothing changed and Stripe retries"},"500":{"description":"Processing failed and was rolled back; Stripe retries"},"503":{"description":"Payments are not set up on this server"}},"security":[],"summary":"Stripe event delivery. No bearer token or session: the Stripe-Signature header (HMAC-SHA256 over the timestamp and raw body, 5-minute tolerance) authorizes it. Handles checkout.session.completed (paid USD top-ups credit the amount; subscription checkouts store the subscription), invoice.paid (a paid USD plan invoice for the stored subscription, whose lines use configured plan Prices or the custom Price of the account, credits amount_paid once as plan credit; a new or renewal invoice first expires the unused plan credit of the period it closes, and an upgrade invoice adds to the open period; other invoices are recorded with a reason and credit nothing), customer.subscription.created and .updated (status, period end, subscription item and Price, ordered by event time) and customer.subscription.deleted (the same, and the unused plan credit of the open period expires). A replayed event is a no-op, and each payment credits once. Live-mode events are recorded and ignored."}},"/v1/agent-links":{"post":{"operationId":"createAgentLink","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentLink"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"},"429":{"description":"Too many requests from this client, or the signup storage cap was reached"},"503":{"description":"Agent signup is off: the server runs without --public-url"}},"security":[],"summary":"Agent signup without an account. Returns approve_url for a person to open, a poll_token, expires_at (Unix seconds, 15 minutes) and poll_interval_seconds. No authentication; rate-limited per client. The person signs in with Google and approves; nothing is granted until then."}},"/v1/agent-links/poll":{"post":{"operationId":"pollAgentLink","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentLinkPoll"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"},"410":{"description":"Token already issued, or the link expired"},"429":{"description":"Too many requests from this client, or the signup storage cap was reached"},"503":{"description":"Agent signup is off: the server runs without --public-url"}},"security":[],"summary":"Poll an agent link: status pending until approved, then status approved with a new API token, token_id and user_id, exactly once. Later polls and expired links answer 410. No authentication; rate-limited per client."}},"/v1/agent-links/{code}":{"get":{"operationId":"getAgentLink","parameters":[{"in":"path","name":"code","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Read an agent access request by the code in its approve_url: agent_name, created_at, expires_at and status (pending, approved, issued or expired). Links approved by another account are not found."}},"/v1/agent-links/{code}/approve":{"post":{"operationId":"approveAgentLink","parameters":[{"in":"path","name":"code","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"},"410":{"description":"The link expired before approval"}},"summary":"Approve an agent access request for the authenticated account. Idempotent for the same account; expired links answer 410. The agent receives its token on its next poll."}},"/v1/billing":{"get":{"operationId":"getBilling","responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Credit and plan: balance_microusd (total), plan_credit_microusd (unused plan credit of the current period, spent first), plan_credit_resets_at (when it expires, the period end) and purchased_credit_microusd (the rest; top-ups never expire). subscription has status, plan (a plan id, custom, or null) and current_period_end. Also plans (id, name, monthly price and the equal monthly credit), the customer price per answer for each collection route (fixed, or metered from delivery cost), top_up_amounts_usd, enterprise_contact, whether online payments are available, the sampling state with next_actions when paused, and the latest 100 ledger entries (plan_credit, plan_credit_expiry, top_up, usage, adjustment, refund). Amounts are integer micro-dollars (1 USD = 1,000,000). Shows prices and consumption, never provider costs or margins. enabled is false when the server runs without billing."}},"/v1/billing/checkout":{"post":{"operationId":"createCheckout","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Checkout"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"},"502":{"description":"Stripe declined the request; only the Stripe error code is returned"},"503":{"description":"Payments are not set up on this server"}},"summary":"Create a Stripe Checkout link for the account holder to open: a plan subscription (the cheapest plan unless plan is given; an account with a custom contract uses its own Price), refused while a subscription is active, trialing or past_due; or a top-up of one of top_up_amounts_usd, which needs such a subscription. The credit changes only when Stripe confirms the payment through the webhook. Returns url, kind, plan, amount_usd and expires_at."}},"/v1/billing/plan":{"post":{"operationId":"changeBillingPlan","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanChange"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"},"502":{"description":"Stripe declined the request; only the Stripe error code is returned"},"503":{"description":"Payments are not set up on this server"}},"summary":"Create a Stripe Customer Portal link that confirms a switch of the current subscription to another plan. An upgrade is charged the prorated difference at once and the amount paid is added as plan credit; a downgrade starts at the end of the period. Needs an active, trialing or past_due subscription whose details Stripe has confirmed, and is refused (409) for an account with a custom contract or already on that plan. Returns url, plan, current_plan and change (upgrade or downgrade)."}},"/v1/billing/portal":{"post":{"operationId":"createBillingPortal","responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"},"502":{"description":"Stripe declined the request; only the Stripe error code is returned"},"503":{"description":"Payments are not set up on this server"}},"summary":"Create a Stripe Customer Portal link for invoices, payment methods and cancellation. Answers 409 until the account has subscribed once."}},"/v1/changes/{id}":{"get":{"operationId":"getChange","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Read the change artifact for a publishing agent"}},"/v1/changes/{id}/decisions":{"get":{"operationId":"listDecisions","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Read evidence-linked follow-up decisions"},"post":{"operationId":"recordDecision","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Decision"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Record retain/revise/revert/wait; actual edits and rollbacks are separate agent actions"}},"/v1/changes/{id}/evaluations":{"get":{"operationId":"listEvaluations","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Read saved before/after evaluations"},"post":{"operationId":"evaluateChange","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Evaluation"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Compare matching recorded conditions after settling; results are descriptive, not causal"}},"/v1/changes/{id}/measurement":{"get":{"operationId":"measurementStatus","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Read frozen pairs, matching baseline/follow-up counts, remaining jobs and next action; no collection occurs"},"post":{"operationId":"planMeasurement","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeasurementPlan"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Freeze target questions, active holdouts, ready engines and baseline window; plans made after publication are explicitly retrospective"}},"/v1/changes/{id}/measurement/waves":{"post":{"operationId":"measurementWave","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeasurementWave"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"402":{"description":"Billing is on and the account has no credit. The message names the next actions: buy credits or subscribe with POST /v1/billing/checkout, or upgrade with POST /v1/billing/plan."},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record; or a ready engine uses a collection route without a price"}},"summary":"Queue a bounded jittered wave for remaining samples; request_id is idempotent and pending jobs prevent duplicate work"}},"/v1/changes/{id}/publication":{"post":{"operationId":"recordPublication","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Publication"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Record externally applied revision; this does not deploy or verify the external site"}},"/v1/connections":{"get":{"operationId":"listConnections","responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Your connections, excluding disconnected ones: provider, status, account label, granted scopes, expiry and the products using each. Never returns credentials."}},"/v1/connections/{id}":{"delete":{"operationId":"disconnectConnection","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Disconnect an account for every product that uses it: revoke the grant at the provider where supported (provider_revoked says whether it confirmed), delete the stored credentials and mark the linked products not connected. DNS records, verifications and registered sites stay in place."}},"/v1/connectors":{"get":{"operationId":"listConnectors","responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Catalog of connection purposes (dns, search_console, traffic, publishing) in display order. Each lists its providers with the exact OAuth scopes requested and the reason for each, whether this installation has registered the provider's app, and planned providers that cannot be connected yet."}},"/v1/jobs/claim":{"post":{"operationId":"claimJob","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Claim"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"403":{"description":"Only the platform worker credential (an operator runs search-optimization worker-token) can lease jobs and submit answers"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Lease one due engine job, from any account, for ten minutes; null when none is due. Each engine and collection route is a queue: the account served least recently goes first, then its earliest due job. An optional collection_route keeps, for example, an API worker off consumer-browser jobs with the same engine name; an optional product_id limits the claim to one product. Each job names its account_id, so a worker can tell one account's failures from a collector failure that reaches every account. Needs the platform worker credential. Held work is skipped and other accounts are still served: while billing is on, jobs whose owner has no balance or whose route has no price; and an account's jobs on a queue during a repeated_failures cooldown. When nothing can be leased, job is null and hold explains the first waiting job and its next_actions."}},"/v1/jobs/{id}/result":{"post":{"operationId":"completeJob","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"403":{"description":"Only the platform worker credential (an operator runs search-optimization worker-token) can lease jobs and submit answers"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Submit a matching lease result; repeated completion returns the original immutable observation. Three failed results in a row within an hour pause that account's jobs on that queue for an hour (hold reason repeated_failures); failures the worker marks raw.failure_scope collector (a local key file, or the same collector failure from two accounts within ten minutes) affect every account and do not count. Needs the platform worker credential. Job results are always recorded as live; a provenance field is ignored. While billing is on, a completed answer is charged at its route price once."}},"/v1/me":{"get":{"operationId":"currentUser","responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Authenticated user: id, display name, email and operator. Email is null until the user signs in with Google or an operator claims it. operator is true for the operator role, which only the host CLI grants (search-optimization set-operator); operators see supplier costs on their own products and may hold a platform worker credential."}},"/v1/observations/{id}":{"get":{"operationId":"getObservation","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Read an owned complete observation and its original evidence, with charged_microusd. Supplier-cost fields (cost_microusd and cost details in raw) are removed except for operators"}},"/v1/observations/{id}/citations":{"post":{"operationId":"repairObservationCitations","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CitationRepair"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Add exact source URLs recovered from retained evidence. Source hash must match the observation. Additions are audited and idempotent; the question is not resubmitted."}},"/v1/observations/{id}/invalidate":{"post":{"operationId":"invalidateObservation","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invalidation"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Exclude an owned collection failure from metrics, retaining the original answer, raw evidence and a durable audit entry. Idempotent; does not requeue the job."}},"/v1/products":{"get":{"operationId":"listProducts","responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"List owned products"},"post":{"operationId":"createProduct","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Register product facts and audience"}},"/v1/products/{id}":{"get":{"operationId":"getProduct","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Read product context for the reasoning agent"}},"/v1/products/{id}/campaigns":{"get":{"operationId":"listCampaigns","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Read saved goal briefs, question panels and explicit engine configurations, evidence, linked changes and next action"},"post":{"operationId":"createCampaign","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignCreate"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Save reviewed questions and exact ready engine configurations in the requested country. New questions are inactive until an agent enables sampling. request_id replay returns the original campaign with HTTP 200. No collection or publication occurs."}},"/v1/products/{id}/campaigns/batch":{"post":{"operationId":"createCampaignSet","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignBatch"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Create one campaign per selected goal atomically, with only goals and request_id required. Replay returns the original set with 200. Question preparation is queued automatically; no collection or publication starts."}},"/v1/products/{id}/campaigns/plan":{"post":{"operationId":"planCampaignSet","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignSetupPlan"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Preview selected goals using optional overrides. Defaults are computed in the core; model question preparation covers audiences and intents in the campaign language."}},"/v1/products/{id}/campaigns/preview":{"post":{"operationId":"previewCampaign","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignBrief"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Validate a typed brief and return editable English starter templates, or native supplied questions. No data or collection is created."}},"/v1/products/{id}/campaigns/setup":{"get":{"operationId":"campaignSetup","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Product-derived defaults and one campaign plan for each supported goal. Does not create data or collect."}},"/v1/products/{id}/campaigns/{campaign}/engines":{"post":{"operationId":"addCampaignEngines","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"in":"path","name":"campaign","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignEngines"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Attach verified engine configurations idempotently. Existing questions and evidence stay frozen. An unknown-country route does not establish visibility in the target country."}},"/v1/products/{id}/campaigns/{campaign}/panel":{"post":{"operationId":"completeCampaignPreparation","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"in":"path","name":"campaign","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignPanel"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Agents can fill initially empty question or engine panels once. Existing nonempty panels remain immutable."}},"/v1/products/{id}/campaigns/{campaign}/question-plan":{"get":{"operationId":"questionPreparation","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"in":"path","name":"campaign","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Get product/campaign context, skill, schema and audience/intent coverage status"},"post":{"operationId":"prepareQuestions","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"in":"path","name":"campaign","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Queue one idempotent model task for an unsampled campaign. Existing measured or linked panels remain frozen."}},"/v1/products/{id}/changes":{"get":{"operationId":"listChanges","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"List concrete proposed and published edits"},"post":{"operationId":"proposeChange","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Change"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Store a complete page replacement or unified diff under an owned campaign, with target questions from that campaign, a baseline hash and evidence IDs"}},"/v1/products/{id}/connections":{"get":{"operationId":"getProductConnections","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Per purpose and provider for this product: status (not_connected, connecting, setting_up, ready, needs_attention or blocked), one next_action (create_connection, authorize with connect_url, connect_dns, wait_for_dns with retry_after, retry_setup or reconnect; null when ready), the set-up resource, dated setup receipts and the connection's account label. Actions that call the API include method, endpoint and body. Never returns credentials."},"post":{"operationId":"createConnection","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectionCreate"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Start connecting a provider for this product and return a connect_url to give to a person. The person opens it, signs in and approves; Search Lab then stores the grant and runs setup by itself. The link works for 7 days or until approval completes. Request IDs are idempotent; a new request ID replaces the pending link for this product and provider. Answers 201 when created and 200 when replayed."}},"/v1/products/{id}/connections/link":{"post":{"operationId":"linkConnection","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectionLink"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"},"502":{"description":"The provider answered with an error; the message names the step and never includes credentials"}},"summary":"Reuse one of your active connections for this product, then run that provider's setup for it. Not available through the dashboard."}},"/v1/products/{id}/connections/setup":{"post":{"operationId":"runConnectionSetup","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectionSetup"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"},"502":{"description":"The provider answered with an error; the message names the step and never includes credentials"}},"summary":"Run or resume setup for this product: find the DNS zone, add verification records, verify the domain, register the site and submit its sitemaps. Safe to rerun: existing records and sites are reused. Purposes default to dns and search_console. Request IDs are idempotent and replay the stored result. Returns the product's connection status."}},"/v1/products/{id}/engines":{"get":{"operationId":"listEngines","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"See supported configurations and explicit unavailable coverage"},"post":{"operationId":"createEngine","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Engine"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Register an engine, surface, location and search mode. While billing is on, collection_route must be in the price list; the 400 lists the priced routes."}},"/v1/products/{id}/engines/{engine}/status":{"put":{"operationId":"setEngineStatus","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"in":"path","name":"engine","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EngineStatus"}}},"required":true},"responses":{"204":{"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Enable or disable a collector configuration"}},"/v1/products/{id}/jobs":{"get":{"operationId":"listJobs","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Inspect latest 1000 jobs; lease secrets excluded"}},"/v1/products/{id}/observations":{"get":{"operationId":"listObservations","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"in":"query","name":"from","schema":{"format":"date-time","type":"string"}},{"in":"query","name":"to","schema":{"format":"date-time","type":"string"}},{"description":"Exact question-language filter; independent of UI locale and country.","in":"query","name":"language","schema":{"default":"unknown","description":"BCP 47 language tag, e.g. en, fr-BE, pl or sr-Latn; unknown preserves unspecified metadata.","type":"string"}},{"description":"Exact engine requested-country filter; does not assert actual location.","in":"query","name":"requested_country","schema":{"type":"string"}},{"description":"Restrict questions and engines to an owned campaign panel.","in":"query","name":"campaign_id","schema":{"type":"string"}},{"in":"query","name":"offset","schema":{"default":0,"minimum":0,"type":"integer"}},{"description":"Read every page of samples for one owned question.","in":"query","name":"question_id","schema":{"type":"string"}},{"in":"query","name":"include_synthetic","schema":{"default":true,"type":"boolean"}},{"description":"Omit raw captures/full answers; return 240-character excerpts, newest first.","in":"query","name":"summary","schema":{"default":false,"type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Read raw evidence; pages of 250, using offset. charged_microusd is what the balance paid for each answer (0 when not charged). Supplier-cost fields are removed except for operators"},"post":{"operationId":"importObservation","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Observation"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Import existing evidence with a stable external_id; preserves first record on replay"}},"/v1/products/{id}/opportunities":{"get":{"operationId":"opportunities","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"in":"query","name":"from","schema":{"format":"date-time","type":"string"}},{"in":"query","name":"to","schema":{"format":"date-time","type":"string"}},{"description":"Exact question-language filter; independent of UI locale and country.","in":"query","name":"language","schema":{"default":"unknown","description":"BCP 47 language tag, e.g. en, fr-BE, pl or sr-Latn; unknown preserves unspecified metadata.","type":"string"}},{"description":"Exact engine requested-country filter; does not assert actual location.","in":"query","name":"requested_country","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Evidence and agent instructions for questions missing owned citations; excludes holdouts and defaults to the last 30 days"}},"/v1/products/{id}/question-groups":{"get":{"operationId":"questionGroups","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"in":"query","name":"from","schema":{"format":"date-time","type":"string"}},{"in":"query","name":"to","schema":{"format":"date-time","type":"string"}},{"description":"Exact question-language filter; independent of UI locale and country.","in":"query","name":"language","schema":{"default":"unknown","description":"BCP 47 language tag, e.g. en, fr-BE, pl or sr-Latn; unknown preserves unspecified metadata.","type":"string"}},{"description":"Exact engine requested-country filter; does not assert actual location.","in":"query","name":"requested_country","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Full-history descriptive rollups by type and question; completed-answer denominators, separate failures and unsampled questions retained"}},"/v1/products/{id}/questions":{"get":{"operationId":"listQuestions","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Read immutable question wording and holdout flags"},"post":{"operationId":"createQuestions","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Questions"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Agent-selected buyer questions; new wording gets a new ID"}},"/v1/products/{id}/questions/{question}/active":{"put":{"operationId":"setQuestionActive","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"in":"path","name":"question","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Active"}}},"required":true},"responses":{"204":{"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Enable or archive a question without rewriting history"}},"/v1/products/{id}/samples":{"post":{"operationId":"sampleNow","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Sample"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"402":{"description":"Billing is on and the account has no credit. The message names the next actions: buy credits or subscribe with POST /v1/billing/checkout, or upgrade with POST /v1/billing/plan."},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record; or a ready engine uses a collection route without a price"}},"summary":"Enqueue selected questions on ready engines; engine_ids empty means all ready engines"}},"/v1/products/{id}/schedule":{"get":{"operationId":"getSchedule","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Inspect sampling schedule"},"put":{"operationId":"setSchedule","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Schedule"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Sample questions without replacement across every ready engine; random execution times within the window. Pausing also prevents queued scheduled jobs from being claimed."}},"/v1/products/{id}/site-checks":{"get":{"operationId":"listSiteChecks","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Latest 20 owned website audits, including evidence, scope and timestamps"},"post":{"operationId":"runSiteCheck","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCheck"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Inspect the product website: bounded public HTTP fetches, robots, sitemaps, page directives, canonical URLs and HTML. Up to six pages; optional paths select priority pages. Request IDs are idempotent. Checks do not prove indexing or ranking."}},"/v1/products/{id}/statistics":{"get":{"operationId":"statistics","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"in":"query","name":"from","schema":{"format":"date-time","type":"string"}},{"in":"query","name":"to","schema":{"format":"date-time","type":"string"}},{"description":"Exact question-language filter; independent of UI locale and country.","in":"query","name":"language","schema":{"default":"unknown","description":"BCP 47 language tag, e.g. en, fr-BE, pl or sr-Latn; unknown preserves unspecified metadata.","type":"string"}},{"description":"Exact engine requested-country filter; does not assert actual location.","in":"query","name":"requested_country","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Per-question/engine/recorded-condition statistics, failures, sample counts, uncertainty and charged_microusd. known_cost_usd and unknown_cost_count are supplier cost, shown to operators only"}},"/v1/products/{id}/trends":{"get":{"operationId":"timeline","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"in":"query","name":"from","schema":{"format":"date-time","type":"string"}},{"in":"query","name":"to","schema":{"format":"date-time","type":"string"}},{"description":"Exact question-language filter; independent of UI locale and country.","in":"query","name":"language","schema":{"default":"unknown","description":"BCP 47 language tag, e.g. en, fr-BE, pl or sr-Latn; unknown preserves unspecified metadata.","type":"string"}},{"description":"Exact engine requested-country filter; does not assert actual location.","in":"query","name":"requested_country","schema":{"type":"string"}},{"description":"Owned immutable panel or configuration filter.","in":"query","name":"campaign_id","schema":{"type":"string"}},{"description":"Owned immutable panel or configuration filter.","in":"query","name":"change_id","schema":{"type":"string"}},{"description":"Owned immutable panel or configuration filter.","in":"query","name":"question_id","schema":{"type":"string"}},{"description":"Owned immutable panel or configuration filter.","in":"query","name":"engine_id","schema":{"type":"string"}},{"in":"query","name":"goal","schema":{"enum":["get_recommended"]}},{"in":"query","name":"aggregate_only","schema":{"default":false,"type":"boolean"}},{"in":"query","name":"bucket","schema":{"default":"day","enum":["day","week"]}}],"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Aggregate target-answer trends with question/engine coverage and optional exact-condition series. Goal and campaign membership is deduplicated; controls and synthetic answers are excluded from aggregates. Before/after aggregate rates weight matching recorded conditions equally. Defaults to 30 days; max 366 days, 10000 points. Excludes synthetic records; failures separate and empty buckets null. Published receipts mark changes; selected change compares exact timestamps excluding settling. Descriptive, not causal or traffic attribution."}},"/v1/question-preparations/claim":{"post":{"operationId":"claimQuestionPreparation","responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Lease one pending model task for ten minutes. At most two attempts. Returns skill, context, schema and previous validation error; never worker credentials. An account token or session leases only its own campaigns. The platform worker credential leases across every account, least recently served account first, then oldest; while billing is on it skips accounts without a balance, and job is null with a hold when only those are waiting."}},"/v1/question-preparations/{campaign}/result":{"post":{"operationId":"completeQuestionPreparation","parameters":[{"in":"path","name":"campaign","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuestionPreparationResult"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Validate native audience/intent coverage and atomically save a complete question panel. A matching completed lease is idempotent. Errors permit at most one automatic retry. Does not collect answers. The platform worker credential may submit for any account; an account only for its own campaigns."}},"/v1/tokens":{"get":{"operationId":"listTokens","responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"List token metadata without token secrets. kind is platform_worker for an operator's platform worker credential (search-optimization worker-token; the only kind that can lease jobs, for every account) and api for every other token."},"post":{"operationId":"createToken","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Named"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{}}},"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Create another revocable token; secret returned once"}},"/v1/tokens/{id}":{"delete":{"operationId":"revokeToken","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Success"},"400":{"description":"Invalid input"},"401":{"description":"Missing or revoked bearer token"},"404":{"description":"Not found in authenticated user account"},"409":{"description":"Conflicting state, stale lease or duplicate record"}},"summary":"Revoke an owned token"}}},"security":[{"BearerAuth":[]}],"servers":[{"url":"/"}]}