{"openapi":"3.1.0","info":{"title":"Rank Prompt Public API","version":"v1","description":"Server-to-server REST API for Rank Prompt brands, reports and prompts. Authenticate with a `Bearer rp_live_...` API key minted from the developer dashboard."},"servers":[{"url":"https://api.rankprompt.com","description":"Production"}],"security":[{"BearerAuth":[]}],"paths":{"/v1/me":{"get":{"tags":["Account"],"summary":"Who am I","description":"Return identity info for the authenticated principal. Always `user_id`, `auth_type`, `plan`, `account_id`, `account_role` and `account_plan`: a key acts in the account that was active when it was created, with its creator's role there. `plan` is the creator's own plan; `account_plan` is that account's.\n\nSensitive metadata fields (`key_prefix`, `scopes`, `allowed_brand_id`) are only included when the key carries the `read:meta` scope.","operationId":"get_me_v1_me_get","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Who am I","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-cost":{"request_units":0,"credits":0}}},"/v1/me/quota":{"get":{"tags":["Account"],"summary":"Current quota","description":"Return the current billing period's request quota (`limit`, `used`, `remaining`) alongside the SKU and `current_period_end`.\n\nThe quota is the pool of the account the key acts in: every key made in that account, the owner's and the team's, draws on it. In a team account only the owner raises it, and `request_quota_exceeded` carries no `details.upgrade_url`.\n\nEquivalent to reading the `X-RP-Quota-*` response headers from any metered call, but without consuming a request unit.","operationId":"get_quota_v1_me_quota_get","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Current quota","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuotaResponse"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-cost":{"request_units":0,"credits":0}}},"/v1/me/credits":{"get":{"tags":["Account"],"summary":"Current credit balance","description":"Return the product-credit balance of the account this API key acts in, across the monthly, API add-on and top-up pools: the key creator's own, or the account owner's for a key created in a team account. Credits fund AI work (report runs, brand-facts research, page and brand audits, AI suggestions). Work on a brand is charged to the brand's owner, so a brand the creator owns draws on the creator's own balance, which a team account key does not show here. Does not consume a request unit.","operationId":"get_credits_v1_me_credits_get","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Current credit balance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditBalance"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-cost":{"request_units":0,"credits":0}}},"/v1/me/credits/purchases":{"post":{"tags":["Account"],"summary":"Buy a credit pack","description":"Buy a pack of credits for the account this key belongs to.\n\nSend `shared_payment_token` and the charge settles on this call: the credits are on the balance by the time it returns, and `status` is `succeeded`. That token comes from the buyer's agent wallet and is scoped to one purchase, so the amount and currency are fixed before it reaches us.\n\nWithout a token nothing is charged. You get `status` `checkout` and a `checkout_url` to hand the buyer, which is the path to use whenever the caller has no wallet of its own.\n\nRetrying with the same token is safe: it settles onto the same payment and grants the credits once.\n\nA key created in a team account gets `403 forbidden`: that account's billing belongs to its owner.","operationId":"purchase_credits_v1_me_credits_purchases_post","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditPurchaseRequest"}}}},"responses":{"201":{"description":"Buy a credit pack","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditPurchase"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:billing","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/me/subscriptions":{"post":{"tags":["Account"],"summary":"Subscribe to a plan","description":"Start a subscription to a dashboard plan for the account this key belongs to.\n\nNothing is charged here. You get `status` `checkout` and a `checkout_url` where the buyer subscribes; if the account qualifies for the free trial, Stripe applies it and `trial_days` says how long. An account offered the first month at half price instead of the trial gets that discount on Starter and Pro while the offer lasts, applied on the same Checkout page; `amount_cents` stays the regular price and `first_charge_cents` says what the first charge will be. If the offer cannot be confirmed for a moment, the call answers `503` with `Retry-After`. Repeating the call for the same plan and interval returns the same link while it is open, and `succeeded` once the buyer has paid and the plan is active.\n\nThis only starts a subscription. An account that already holds a plan gets `already_subscribed` and a `manage_url`, since upgrades and downgrades are settled in the app.\n\nA key created in a team account gets `403 forbidden`: that account's billing belongs to its owner.","operationId":"start_subscription_v1_me_subscriptions_post","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequest"}}}},"responses":{"201":{"description":"Subscribe to a plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionCheckout"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:billing","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/me/usage":{"get":{"tags":["Account"],"summary":"Historical usage","description":"Aggregate request units, credits and request counts for the authenticated user over an arbitrary `[from, to)` window (UTC, ISO-8601).\n\nDefaults to the last 30 days; the maximum window is 366 days.\n\nIt counts every call the user made, with any of their keys. Pass `account_id` to count only the calls made with the keys that act in that account: the user's own `user_id`, or a team account they are an active member of (`GET /v1/me` returns the `account_id` this key acts in). Any other id is `404 not_found`; `503 service_unavailable` when the usage cannot be read, to retry.\n\nResponse shape:\n- `total_*`: flat counters for the whole window.\n- `by_day`: per-day rollup (one bucket per UTC calendar day).\n- `by_endpoint`: top 50 endpoints by request count.","operationId":"get_usage_v1_me_usage_get","parameters":[{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Inclusive window start (UTC ISO-8601). Defaults to `to - 30d`.","title":"From"},"description":"Inclusive window start (UTC ISO-8601). Defaults to `to - 30d`."},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Exclusive window end (UTC ISO-8601). Defaults to now.","title":"To"},"description":"Exclusive window end (UTC ISO-8601). Defaults to now."},{"name":"account_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Only the calls made with the keys that act in this account: your `user_id`, or a team account you are an active member of.","title":"Account Id"},"description":"Only the calls made with the keys that act in this account: your `user_id`, or a team account you are an active member of."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Historical usage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageResponse"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-cost":{"request_units":0,"credits":0}}},"/v1/brands":{"get":{"tags":["Brands"],"summary":"List brands","description":"List the brands of the account the key acts in, newest first. Cursor-paginated. A key created in your own account lists the brands you own; a key created in a team account lists the brands of that account your seat reaches.\n\nPass `access=all` to list every brand the key's creator can access in any account, adding the ones shared through a team seat (an agency member's clients, for example). Those brands can be read with the same key, and edited where the seat's role allows it; plan-gated features follow the brand owner's plan.\n\nIf the API key is restricted to a single brand, only that brand is returned.\n\nOptional `search` performs a case-insensitive substring match on `name`.","operationId":"list_brands_v1_brands_get","parameters":[{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Case-insensitive substring match on `name`.","title":"Search"},"description":"Case-insensitive substring match on `name`."},{"name":"access","in":"query","required":false,"schema":{"enum":["owned","all"],"type":"string","description":"`owned` lists the brands of the account the key acts in; `all` adds every brand shared with the key's creator through a team seat.","default":"owned","title":"Access"},"description":"`owned` lists the brands of the account the key acts in; `all` adds every brand shared with the key's creator through a team seat."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Page size (default 20, max 100).","default":20,"title":"Limit"},"description":"Page size (default 20, max 100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Continuation token from a previous response's `next_cursor`.","title":"Cursor"},"description":"Continuation token from a previous response's `next_cursor`."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned brands","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:brands","x-rankprompt-cost":{"request_units":1,"credits":0}},"post":{"tags":["Brands"],"summary":"Create a brand","description":"Create a brand owned by the key's creator. It belongs to the creator's own account even when the key acts in a team account, so a team key finds it with `access=all`. The new brand starts without researched facts. Call `POST /v1/brands/{brand_id}/facts` to enqueue the research job.\n\nAPI keys restricted to a single brand cannot create new brands and are rejected with `brand_not_authorized`.","operationId":"create_brand_v1_brands_post","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBrandRequest"}}}},"responses":{"201":{"description":"Created a brand","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Brand"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:brands","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}":{"get":{"tags":["Brands"],"summary":"Retrieve a brand","description":"Return a single brand by id, including its aliases, categories and primary market (`country`, `language`).","operationId":"get_brand_v1_brands__brand_id__get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned a brand","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Brand"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:brands","x-rankprompt-cost":{"request_units":1,"credits":0}},"patch":{"tags":["Brands"],"summary":"Update a brand","description":"Partial update: only the fields you send are written. An empty body is a valid no-op.","operationId":"update_brand_v1_brands__brand_id__patch","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateBrandRequest"}}}},"responses":{"200":{"description":"Updated a brand","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Brand"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:brands","x-rankprompt-cost":{"request_units":1,"credits":0}},"delete":{"tags":["Brands"],"summary":"Delete a brand","description":"Schedule the brand for deletion. It is hidden immediately and all its data (reports, prompts, results, scheduled reports, region configs, shares, ...) is cascade-deleted by a background job after a short grace window. Idempotent: deleting an already-scheduled brand also returns `204`.","operationId":"delete_brand_v1_brands__brand_id__delete","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"204":{"description":"Brand scheduled for deletion.","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:brands","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/scheduled-deletion":{"delete":{"tags":["Brands"],"summary":"Restore a brand","description":"Cancel the brand's scheduled deletion while its grace window lasts: the brand and all its data come back as they were. Owner only. Idempotent: a brand not scheduled for deletion also returns `204`. The brand takes back its place under the owner's plan, unless a brand made since took it (`402 insufficient_credits` with `details.reason` `plan_limit`): delete that one or upgrade first. A brand already being purged answers `409 conflict`, and one purged `404`.","operationId":"restore_brand_v1_brands__brand_id__scheduled_deletion_delete","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"204":{"description":"Brand restored.","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:brands","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/facts":{"get":{"tags":["Brand facts"],"summary":"Retrieve brand facts","description":"Return the brand's latest researched facts (description, industry, value proposition, key facts, and so on).\n\nReturns `404 facts_not_generated` if no research has produced facts yet. `POST` this same path to enqueue a research job.","operationId":"get_brand_facts_v1_brands__brand_id__facts_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned brand facts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandFacts"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:brands","x-rankprompt-cost":{"request_units":1,"credits":0}},"post":{"tags":["Brand facts"],"summary":"Regenerate brand facts","description":"Enqueue a brand-facts research job and return its `job_id` immediately (`202 Accepted`). The job runs in the background.\n\nWorkflow:\n1. `POST /v1/brands/{brand_id}/facts`: returns `{ job_id }`.\n2. `GET /v1/jobs/{job_id}`: poll until `status` is `completed`.\n3. `GET /v1/brands/{brand_id}/facts`: read the refreshed facts.\n\n**Pricing:** The first research run for a brand (no prior facts of any kind) is free. Subsequent re-research runs cost 1 credit. Credits are debited when the job starts. Failed runs do not auto-refund.\n\nRate limited more tightly than most endpoints; the exact limit is published as `x-rankprompt-rate-limit` on this operation. See `429 rate_limit_exceeded` response.","operationId":"regenerate_brand_facts_v1_brands__brand_id__facts_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"202":{"description":"Brand-facts research job dispatched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandFactsRegenerateDispatched"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"402":{"description":"Not enough credits to complete this operation","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"insufficient_credits","message":"Not enough credits to complete this operation"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:brands","x-rankprompt-cost":{"request_units":2,"credits":1},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}},"patch":{"tags":["Brand facts"],"summary":"Update brand facts","description":"Edit the brand's facts in place. Useful for hand-tuning facts after the asynchronous research has produced them.\n\nPATCH semantics:\n- Fields you send are merged into the persisted blob.\n- Sending `null` clears a field.\n- `key_facts` is replaced as a whole (not merged item-by-item).\n\nWriting a non-empty `description` sets `research_status` to `complete`, so a brand the research could not read is ready for reports.","operationId":"update_brand_facts_v1_brands__brand_id__facts_patch","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandFactsUpdate"}}}},"responses":{"200":{"description":"Updated brand facts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandFacts"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:brands","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/alias-suggestions":{"get":{"tags":["Alias suggestions"],"summary":"List alias suggestions","description":"Return the brand's pending alias suggestions: alternate names the analyzer surfaced from recent reports that look like they could be referring to the brand.\n\nAccept (`POST .../acceptances`) to add the name to `brand_aliases` so future analyses count it as a brand mention. Dismiss to silence it permanently.","operationId":"list_alias_suggestions_v1_brands__brand_id__alias_suggestions_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned alias suggestions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AliasSuggestionList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:brands","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/alias-suggestions/{business_name}":{"delete":{"tags":["Alias suggestions"],"summary":"Dismiss an alias suggestion","description":"Permanently dismiss an alias suggestion so the analyzer won't re-surface it on future reports.\n\nIdempotent on already-dismissed or unknown names.","operationId":"dismiss_alias_suggestion_v1_brands__brand_id__alias_suggestions__business_name__delete","parameters":[{"name":"business_name","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"description":"Business name to dismiss (URL-encode special characters).","title":"Business Name"},"description":"Business name to dismiss (URL-encode special characters)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"204":{"description":"Suggestion dismissed.","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:brands","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/alias-suggestions/{business_name}/acceptances":{"post":{"tags":["Alias suggestions"],"summary":"Accept an alias suggestion","description":"Accept a suggestion: the `business_name` is appended to the brand's `brand_aliases` and removed from the pending list. Past reports are recomputed in the background (no engine calls, no credits), so their visibility scores count the new alias within a few minutes; there is nothing to re-run.\n\nErrors:\n- `409 alias_already_accepted`: the alias is already present.\n- `400 validation_error`: the brand has reached the maximum of 50 aliases; remove one via `PATCH /v1/brands/{id}` first.","operationId":"accept_alias_suggestion_v1_brands__brand_id__alias_suggestions__business_name__acceptances_post","parameters":[{"name":"business_name","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"description":"Suggestion to accept (URL-encode special characters).","title":"Business Name"},"description":"Suggestion to accept (URL-encode special characters)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"201":{"description":"Suggestion accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AliasSuggestionAccepted"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:brands","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/reports":{"get":{"tags":["Reports"],"summary":"List reports","description":"List reports under a brand (newest first). Cursor-paginated.\n\nThe `brand_id` query parameter is **required**.\n\nFilters compose with AND: `status`, `search` (case-insensitive on `name`), `scheduled_report_id`, `batch_id`, `tracker_id`, `run_id`, `market_id` and `place` (both repeat for several; a report matches one of the markets named in one of the places named).\n\nA report is the result of one run in one market. A report created with `POST /v1/reports` that has not run yet lists as `draft`; once it runs, its report keeps that id.","operationId":"list_reports_v1_reports_get","parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"enum":["draft","processing","completed","failed"],"type":"string"},{"type":"null"}],"description":"Filter by report lifecycle status.","title":"Status"},"description":"Filter by report lifecycle status."},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Case-insensitive substring match on `name`.","title":"Search"},"description":"Case-insensitive substring match on `name`."},{"name":"scheduled_report_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":64},{"type":"null"}],"description":"Filter to reports generated by a specific schedule (UUID).","title":"Scheduled Report Id"},"description":"Filter to reports generated by a specific schedule (UUID)."},{"name":"batch_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":64},{"type":"null"}],"description":"Filter to reports from a specific scheduled-run batch (UUID).","title":"Batch Id"},"description":"Filter to reports from a specific scheduled-run batch (UUID)."},{"name":"tracker_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter to the reports of one tracker (the report's `tracker_id`), one-off or scheduled.","title":"Tracker Id"},"description":"Filter to the reports of one tracker (the report's `tracker_id`), one-off or scheduled."},{"name":"run_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter to the reports of one run (the report's `run_id`).","title":"Run Id"},"description":"Filter to the reports of one run (the report's `run_id`)."},{"name":"market_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":200},{"type":"null"}],"description":"Only the runs in these markets (a report's `market_id`, a region config's `id`); repeat the parameter for several.","title":"Market Id"},"description":"Only the runs in these markets (a report's `market_id`, a region config's `id`); repeat the parameter for several."},{"name":"place","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","minLength":1,"maxLength":300},"maxItems":200},{"type":"null"}],"description":"Only the runs in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake, `australia|emerald|victoria`), across every tracker; repeat the parameter for several.","title":"Place"},"description":"Only the runs in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake, `australia|emerald|victoria`), across every tracker; repeat the parameter for several."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Page size (default 20, max 100).","default":20,"title":"Limit"},"description":"Page size (default 20, max 100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Continuation token from a previous response's `next_cursor`.","title":"Cursor"},"description":"Continuation token from a previous response's `next_cursor`."},{"name":"brand_id","in":"query","required":true,"schema":{"type":"string","description":"Brand UUID to scope the listing. **Required.**","examples":["b3d2c1a0-1234-4abc-9def-0123456789ab"],"title":"Brand Id"},"description":"Brand UUID to scope the listing. **Required.**"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned reports","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:reports","x-rankprompt-cost":{"request_units":1,"credits":0}},"post":{"tags":["Reports"],"summary":"Create a report","description":"Create a report in `draft` status. No analysis is dispatched yet, so you can edit prompts before spending credits.\n\nWith `region_config_id` the report copies that region config's market (country, city, language and AI platforms you leave out): it is a one-off copy and does not join the scheduled report's runs.\n\nWorkflow:\n0. **Required before step 3**: `POST /v1/brands/{brand_id}/facts` to research the brand asynchronously, or `PATCH /v1/brands/{brand_id}/facts` with `{\"description\": \"...\"}` to set them manually.\n1. `POST /v1/reports` (this endpoint): returns a draft.\n2. `POST /v1/reports/{id}/prompts`: seed prompts (manual or auto-generated).\n3. `POST /v1/reports/{id}/runs`: dispatch the analysis (returns `job_id`).\n4. `GET /v1/jobs/{job_id}`: poll until `completed`.\n5. `GET /v1/reports/{id}`: read the final report (prompts + results inlined).\n\nRequires the brand to have `name` and `website` set; returns `422 validation_error` otherwise.","operationId":"create_report_v1_reports_post","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportCreate"}}}},"responses":{"201":{"description":"Draft report created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Report"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:reports","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/reports/{report_id}":{"get":{"tags":["Reports"],"summary":"Retrieve a report","description":"Return a single report with its `prompts` and per-platform `prompts[*].results` inlined. One call covers everything you need to render the full report. No follow-up requests required.\n\nEach result carries the engine's full answer in `response`, which is most of the payload. Pass `include_responses=false` to leave it out when you only need who appeared, the ranks and the citations.","operationId":"get_report_v1_reports__report_id__get","parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"string","description":"Report UUID.","title":"Report Id"},"description":"Report UUID."},{"name":"include_responses","in":"query","required":false,"schema":{"type":"boolean","description":"`false` leaves out each result's full answer text (`response` is null).","default":true,"title":"Include Responses"},"description":"`false` leaves out each result's full answer text (`response` is null)."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned a report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportDetail"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:reports","x-rankprompt-cost":{"request_units":3,"credits":0}},"patch":{"tags":["Reports"],"summary":"Update a report","description":"Partial update of a report. Mutability is gated per-field by the report's lifecycle state:\n\n- `draft`: every field is mutable.\n- `completed` / `failed`: only `name` is mutable (cosmetic). Editing `location`, `country`, `language` or `ai_platforms` returns `409 report_not_modifiable`; create a new report to re-run with different parameters.\n- `processing`: nothing is mutable; returns `409 report_not_modifiable` while the run is in progress.","operationId":"update_report_v1_reports__report_id__patch","parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"string","description":"Report UUID.","title":"Report Id"},"description":"Report UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportUpdate"}}}},"responses":{"200":{"description":"Updated a report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Report"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:reports","x-rankprompt-cost":{"request_units":1,"credits":0}},"delete":{"tags":["Reports"],"summary":"Delete a report","description":"Permanently delete a report and its prompts and results. A one-off report goes with the definition it ran from (a draft, or a report run once more after a failure, goes with every run of it); a report of a scheduled run removes that run's result only.\n\nA report that is `processing` cannot be deleted until it finishes: `409 report_not_modifiable`. Deleting a one-off report that ran more than once needs OWNER access on the brand.","operationId":"delete_report_v1_reports__report_id__delete","parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"string","description":"Report UUID.","title":"Report Id"},"description":"Report UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"204":{"description":"Report deleted.","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:reports","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/reports/{report_id}/ai-analysis":{"get":{"tags":["Reports"],"summary":"Get AI analysis","description":"Return the cached AI analysis for a completed report:\n\n- `ai_suggestion`: free-text recommendations (LLM-authored).\n- `ai_analysis`: structured JSON (themes, opportunities, gaps).\n\nBoth are null until `POST /v1/reports/{report_id}/ai-suggestions` runs on the completed report; that call writes them and turns them into tasks. The first suggestion per brand is free.","operationId":"get_ai_analysis_v1_reports__report_id__ai_analysis_get","parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"string","description":"Report UUID.","title":"Report Id"},"description":"Report UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned AI analysis","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportAiAnalysis"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:reports","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/reports/{report_id}/summary":{"get":{"tags":["Reports"],"summary":"Get report summary","description":"Return a compact one-call digest of a report: the headline metrics (`visibility_score`, `total_results`, `ranked_prompts`, `ai_platforms`), the visibility per engine (`platform_breakdown`) and per prompt category (`category_breakdown`), plus the LLM commentary (`ai_suggestion`, `ai_analysis`), and the score's noise band with the change since the previous run, counted only over the answers both runs asked (`visibility_band`).\n\nUse this when you want the gist without the full per-prompt breakdown. For the citations and per-platform answers, use `GET /v1/reports/{id}` (heavier; inlines every prompt and result).","operationId":"get_report_summary_v1_reports__report_id__summary_get","parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"string","description":"Report UUID.","title":"Report Id"},"description":"Report UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned report summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportSummary"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:reports","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/reports/{report_id}/prompts":{"get":{"tags":["Reports"],"summary":"List report prompts","description":"List every prompt attached to a report (capped at `MAX_PROMPTS_PER_REPORT = 50`). This returns prompts only; to get each prompt with its per-platform `results` inlined, use `GET /v1/reports/{id}` instead.","operationId":"list_prompts_v1_reports__report_id__prompts_get","parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"string","description":"Report UUID.","title":"Report Id"},"description":"Report UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned report prompts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromptList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:reports","x-rankprompt-cost":{"request_units":1,"credits":0}},"post":{"tags":["Reports"],"summary":"Add report prompts","description":"Add prompts to a draft (or previously failed) report. Provide exactly one of:\n\n- `prompts`: explicit list of `{ prompt_text, category }` objects. Works on any brand, including brands without facts.\n- `auto_generate`: let the LLM seed prompts from the brand's facts. Synchronous; may take 10-30s. **Requires the brand to have facts** set. Returns `409 report_not_modifiable` if the report is `processing` or `completed`. `replace: true` (with `auto_generate` only) replaces the report's prompts instead of adding to them.\n\nRate limited more tightly than most endpoints; the exact limit is published as `x-rankprompt-rate-limit` on this operation. Applies to both the manual and `auto_generate` modes.","operationId":"create_prompts_v1_reports__report_id__prompts_post","parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"string","description":"Report UUID.","title":"Report Id"},"description":"Report UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromptBulkCreate"}}}},"responses":{"201":{"description":"Prompts created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromptBulkCreated"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:prompts","x-rankprompt-cost":{"request_units":5,"credits":0},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}},"delete":{"tags":["Reports"],"summary":"Clear report prompts","description":"Delete the prompts named in `prompt_ids`, or every prompt attached to a report when it is omitted. Ids that are not this report's prompts are skipped. The parent report must be `draft` or `failed`; otherwise returns `409 report_not_modifiable`.","operationId":"delete_all_prompts_v1_reports__report_id__prompts_delete","parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"string","description":"Report UUID.","title":"Report Id"},"description":"Report UUID."},{"name":"prompt_ids","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":50},{"type":"null"}],"description":"Only these prompts; repeat for several. Omit to delete every prompt of the report.","title":"Prompt Ids"},"description":"Only these prompts; repeat for several. Omit to delete every prompt of the report."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"204":{"description":"Clear report prompts","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:prompts","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/reports/{report_id}/runs":{"post":{"tags":["Reports"],"summary":"Run analysis","description":"Dispatch the visibility-analysis job for a draft (or previously failed) report. Returns `202 Accepted` with a `job_id` to poll.\n\nA draft's report keeps the draft's id. A failed report is retried on the same report, and only its run's failed markets are charged again; when its prompts changed since it failed, a new run starts instead and `report_id` names the new report. The `Idempotency-Key` of the call also keys the run.\n\nPreconditions:\n- Report status is `draft` or `failed`.\n- At least one prompt is attached.\n- Brand has facts set (`brand_info.description` non-empty).\nTrack progress via `GET /v1/jobs/{job_id}`. Once the job is `completed`, `GET /v1/reports/{id}` returns the populated report.\n\nRate limited more tightly than most endpoints; the exact limit is published as `x-rankprompt-rate-limit` on this operation. See `429 rate_limit_exceeded` response.","operationId":"run_report_v1_reports__report_id__runs_post","parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"string","description":"Report UUID.","title":"Report Id"},"description":"Report UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportRun","default":{}}}}},"responses":{"202":{"description":"Analysis job dispatched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportRunDispatched"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"402":{"description":"Not enough credits to complete this operation","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"insufficient_credits","message":"Not enough credits to complete this operation"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:reports","x-rankprompt-cost":{"request_units":5,"credits":0},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}}},"/v1/reports/{report_id}/prompts/{prompt_id}":{"patch":{"tags":["Reports"],"summary":"Update a report prompt","description":"Partial update of a prompt's `prompt_text` and/or `category`. The parent report must be `draft` or `failed`. Otherwise returns `409 report_not_modifiable`.","operationId":"update_prompt_v1_reports__report_id__prompts__prompt_id__patch","parameters":[{"name":"prompt_id","in":"path","required":true,"schema":{"type":"string","description":"Prompt UUID.","title":"Prompt Id"},"description":"Prompt UUID."},{"name":"report_id","in":"path","required":true,"schema":{"type":"string","description":"Report UUID.","title":"Report Id"},"description":"Report UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromptUpdate"}}}},"responses":{"200":{"description":"Updated a report prompt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Prompt"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:prompts","x-rankprompt-cost":{"request_units":1,"credits":0}},"delete":{"tags":["Reports"],"summary":"Delete a report prompt","description":"Delete a single prompt. The parent report must be `draft` or `failed`; otherwise returns `409 report_not_modifiable`.","operationId":"delete_prompt_v1_reports__report_id__prompts__prompt_id__delete","parameters":[{"name":"prompt_id","in":"path","required":true,"schema":{"type":"string","description":"Prompt UUID.","title":"Prompt Id"},"description":"Prompt UUID."},{"name":"report_id","in":"path","required":true,"schema":{"type":"string","description":"Report UUID.","title":"Report Id"},"description":"Report UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"204":{"description":"Prompt deleted.","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:prompts","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/reports/{report_id}/shares":{"get":{"tags":["Shares"],"summary":"List shares","description":"List the caller's non-expired public share links for a report (newest first).\n\nOnly shares created by the authenticated principal are returned: shares created by other teammates are not visible.","operationId":"list_report_shares_v1_reports__report_id__shares_get","parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"string","description":"Report UUID.","title":"Report Id"},"description":"Report UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned shares","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportShareList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:reports","x-rankprompt-cost":{"request_units":1,"credits":0}},"post":{"tags":["Shares"],"summary":"Create a share","description":"Create a public share link for a completed report. If the caller already has a share for this report, the snapshot is rebuilt and the **same** token is returned (`is_existing=true`).\n\nPass `rotate=true` to drop the caller's existing shares and mint a fresh token (use this when a previous link may have been leaked).\n\nDefaults: 30-day expiry, no rotation. The caller's account-level white-label branding is applied automatically.\n\nReturns `400 validation_error` once a report already has 50 active shares (counted across all teammates), and while the report is still `processing`.","operationId":"create_report_share_v1_reports__report_id__shares_post","parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"string","description":"Report UUID.","title":"Report Id"},"description":"Report UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ReportShareCreate"},{"type":"null"}],"description":"Share config (optional; defaults to 30-day expiry, no rotation).","title":"Payload"}}}},"responses":{"201":{"description":"Created a share","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportShare"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:reports","x-rankprompt-cost":{"request_units":3,"credits":0}},"delete":{"tags":["Shares"],"summary":"Revoke shares","description":"Revoke every share link the caller owns for this report. Idempotent: calling it again on a report with no shares returns `204` no-op.\n\nCannot remove shares created by other teammates.","operationId":"delete_report_shares_v1_reports__report_id__shares_delete","parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"string","description":"Report UUID.","title":"Report Id"},"description":"Report UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"204":{"description":"Revoke shares","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:reports","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/reports/{report_id}/shares/{share_id}":{"patch":{"tags":["Shares"],"summary":"Extend a share","description":"Reset a share's `expires_at` to `now + expiration_days` (1-365). Anchored to **now**: the new expiry is predictable regardless of any remaining time on the previous window.\n\nOnly the share's owner can extend it.","operationId":"update_report_share_v1_reports__report_id__shares__share_id__patch","parameters":[{"name":"share_id","in":"path","required":true,"schema":{"type":"string","description":"Share id (UUID).","title":"Share Id"},"description":"Share id (UUID)."},{"name":"report_id","in":"path","required":true,"schema":{"type":"string","description":"Report UUID.","title":"Report Id"},"description":"Report UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportShareUpdate"}}}},"responses":{"200":{"description":"Extend a share","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportShare"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:reports","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/region-configs":{"get":{"tags":["Region configs"],"summary":"List region configs","description":"List region configs under a brand (newest first). Cursor-paginated.\n\nThe `brand_id` query parameter is **required**.\n\nFilters compose with AND: `is_active`, `search` (case-insensitive substring on `name`).","operationId":"list_region_configs_v1_region_configs_get","parameters":[{"name":"is_active","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Optional: filter by active state.","title":"Is Active"},"description":"Optional: filter by active state."},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Case-insensitive substring match on `name`.","title":"Search"},"description":"Case-insensitive substring match on `name`."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Page size (default 20, max 100).","default":20,"title":"Limit"},"description":"Page size (default 20, max 100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Continuation token from a previous response's `next_cursor`.","title":"Cursor"},"description":"Continuation token from a previous response's `next_cursor`."},{"name":"brand_id","in":"query","required":true,"schema":{"type":"string","description":"Brand UUID to scope the listing. **Required.**","examples":["b3d2c1a0-1234-4abc-9def-0123456789ab"],"title":"Brand Id"},"description":"Brand UUID to scope the listing. **Required.**"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned region configs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegionConfigList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:region-configs","x-rankprompt-cost":{"request_units":1,"credits":0}},"post":{"tags":["Region configs"],"summary":"Create a region config","description":"Create a region config under a brand. A region config defines a (country, language, location, AI-platforms) target. One report is materialised per region config every time the parent schedule ticks.\n\n`scheduled_report_id` is required: create the schedule first via `POST /v1/scheduled-reports`, then pass its id here. A schedule has at most the brand owner's plan cap of region configs; past it the call answers `400 validation_error`. A schedule that already measures the same place (country and city) in the same language answers that region config instead of a second one.\n\nWith `source_report_id` and `copy_report_prompts: true` the config is seeded with that report's prompts in the same call, which is how a one-off report becomes a tracked market.\n\nReturns `404 not_found` if the referenced schedule or source report belongs to a different brand.","operationId":"create_region_config_v1_region_configs_post","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegionConfigCreate"}}}},"responses":{"201":{"description":"Region config created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegionConfig"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:region-configs","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/region-configs/{region_config_id}":{"get":{"tags":["Region configs"],"summary":"Retrieve a region config","description":"Return a single region config by id, including its `country`, `language`, `location`, attached `scheduled_report_id`, `ai_platforms` and `prompts_count`.","operationId":"get_region_config_v1_region_configs__region_config_id__get","parameters":[{"name":"region_config_id","in":"path","required":true,"schema":{"type":"string","description":"Region config UUID.","title":"Region Config Id"},"description":"Region config UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned a region config","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegionConfig"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:region-configs","x-rankprompt-cost":{"request_units":1,"credits":0}},"patch":{"tags":["Region configs"],"summary":"Update a region config","description":"Partial update of a region config. Only the fields you send are written. Useful to toggle `is_active` or adjust the `ai_platforms` list between runs.\n\nSetting `is_active: true` on a paused region config returns `400 validation_error` when its schedule already has the brand owner's plan cap of active region configs.","operationId":"update_region_config_v1_region_configs__region_config_id__patch","parameters":[{"name":"region_config_id","in":"path","required":true,"schema":{"type":"string","description":"Region config UUID.","title":"Region Config Id"},"description":"Region config UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegionConfigUpdate"}}}},"responses":{"200":{"description":"Updated a region config","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegionConfig"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:region-configs","x-rankprompt-cost":{"request_units":1,"credits":0}},"delete":{"tags":["Region configs"],"summary":"Delete a region config","description":"Remove a region config from its schedule. One that never ran is removed (it no longer lists). One that ran is paused instead (`is_active` false), so its historical reports stay: it no longer runs, still lists, and PATCH `is_active` true resumes it.\n\nThis is also the canonical way to remove a region from a schedule. There is no separate detach endpoint.\n\nRequires OWNER access on the brand.","operationId":"delete_region_config_v1_region_configs__region_config_id__delete","parameters":[{"name":"region_config_id","in":"path","required":true,"schema":{"type":"string","description":"Region config UUID.","title":"Region Config Id"},"description":"Region config UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"204":{"description":"Region config deleted, or paused when it has runs.","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:region-configs","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/region-configs/{region_config_id}/prompts":{"get":{"tags":["Region configs"],"summary":"List region config prompts","description":"Return every prompt the region config asks (newest first), paused ones included: its own and the ones every region config of the schedule shares (`shared: true`). `prompt_text` is the stored text, where `{city}` stands for each region config's city; `rendered_text` is what this one asks. At most 50 are active.","operationId":"list_prompts_v1_region_configs__region_config_id__prompts_get","parameters":[{"name":"region_config_id","in":"path","required":true,"schema":{"type":"string","description":"Region config UUID.","title":"Region Config Id"},"description":"Region config UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned region config prompts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegionConfigPromptList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:region-configs","x-rankprompt-cost":{"request_units":1,"credits":0}},"post":{"tags":["Region configs"],"summary":"Add region config prompts","description":"Add prompts to a region config. Each prompt requires a `prompt_text` and a non-empty `category` (free-form taxonomy bucket used for per-category analytics on the resulting reports. Pick a stable string per bucket. The category is the topic the prompt is about, e.g. `CRM Software`, `Marketing Automation`, `Running Shoes`).\n\nA text the config already asks (compared trimmed, case-insensitive, with runs of spaces as one), its own or one every region config shares, is returned as it is instead of added twice, a paused one with that text is resumed, and a text sent twice in one call is added once. The response lists one prompt per distinct text, in the order sent.\n\nReturns `400 validation_error` if the active total would exceed 50.\n\nAdding the first prompt to an inactive region config auto-reactivates it, unless its schedule already has the plan's cap of active region configs: then it stays paused.","operationId":"create_prompts_v1_region_configs__region_config_id__prompts_post","parameters":[{"name":"region_config_id","in":"path","required":true,"schema":{"type":"string","description":"Region config UUID.","title":"Region Config Id"},"description":"Region config UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegionConfigPromptBulkCreate"}}}},"responses":{"201":{"description":"Prompts created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegionConfigPromptBulkCreated"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:region-configs","x-rankprompt-cost":{"request_units":2,"credits":0}},"delete":{"tags":["Region configs"],"summary":"Clear region config prompts","description":"Soft-delete every active prompt the region config asks (rows are kept with `disabled=true`), the ones every region config shares included, which stop in all of them.\n\nUseful as a step before re-seeding via `POST /v1/region-configs/{id}/prompts`.","operationId":"delete_all_prompts_v1_region_configs__region_config_id__prompts_delete","parameters":[{"name":"region_config_id","in":"path","required":true,"schema":{"type":"string","description":"Region config UUID.","title":"Region Config Id"},"description":"Region config UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"204":{"description":"Prompts disabled.","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:region-configs","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/region-configs/{region_config_id}/prompts/{prompt_id}":{"patch":{"tags":["Region configs"],"summary":"Update a region config prompt","description":"Partial update of a region-config prompt's `prompt_text`, `category` or `disabled`. A prompt every region config of the schedule shares (`shared: true`) changes in all of them. `mode` says how a new `prompt_text` is read: `reword` (default) keeps the prompt and its history; `new_question` pauses it and returns the prompt that replaces it, with a new id. A `prompt_text` another active prompt of the region config already asks (compared trimmed, case-insensitive, with runs of spaces as one) returns `400 validation_error`.","operationId":"update_prompt_v1_region_configs__region_config_id__prompts__prompt_id__patch","parameters":[{"name":"prompt_id","in":"path","required":true,"schema":{"type":"string","description":"Region config prompt UUID.","title":"Prompt Id"},"description":"Region config prompt UUID."},{"name":"region_config_id","in":"path","required":true,"schema":{"type":"string","description":"Region config UUID.","title":"Region Config Id"},"description":"Region config UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegionConfigPromptUpdate"}}}},"responses":{"200":{"description":"Updated a region config prompt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegionConfigPrompt"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:region-configs","x-rankprompt-cost":{"request_units":1,"credits":0}},"delete":{"tags":["Region configs"],"summary":"Delete a region config prompt","description":"Soft-delete (disable) a region-config prompt. The row is retained for analytics history but excluded from future scheduled runs; a prompt every region config shares stops in all of them.\n\nAlready-completed reports remain unchanged.","operationId":"delete_prompt_v1_region_configs__region_config_id__prompts__prompt_id__delete","parameters":[{"name":"prompt_id","in":"path","required":true,"schema":{"type":"string","description":"Region config prompt UUID.","title":"Prompt Id"},"description":"Region config prompt UUID."},{"name":"region_config_id","in":"path","required":true,"schema":{"type":"string","description":"Region config UUID.","title":"Region Config Id"},"description":"Region config UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"204":{"description":"Prompt deleted.","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:region-configs","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/locations":{"get":{"tags":["Locations"],"summary":"List the brand's places","description":"The brand's real places (stores, offices, branches), newest first, cursor-paginated: what a report measures as a market when it should ask where the business really is. `include_archived` adds archived ones.","operationId":"list_locations_v1_brands__brand_id__locations_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"include_archived","in":"query","required":false,"schema":{"type":"boolean","description":"`true` adds archived places.","default":false,"title":"Include Archived"},"description":"`true` adds archived places."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Page size (default 20, max 100).","default":20,"title":"Limit"},"description":"Page size (default 20, max 100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Continuation token from a previous response's `next_cursor`.","title":"Cursor"},"description":"Continuation token from a previous response's `next_cursor`."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned the brand's places","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:locations","x-rankprompt-cost":{"request_units":1,"credits":0}},"post":{"tags":["Locations"],"summary":"Add a place","description":"Add one of the brand's real places by hand. A place with a Google place id the brand has already comes back as it is. Free; the brand owner's plan caps how many active places a brand has (`402 insufficient_credits` with `details.reason` `plan_limit`).","operationId":"create_location_v1_brands__brand_id__locations_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationCreate"}}}},"responses":{"201":{"description":"Add a place","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Location"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:locations","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/locations/{location_id}":{"patch":{"tags":["Locations"],"summary":"Update or archive a place","description":"Change a place, make it the main one (`is_primary`), archive it (`status: archived`) or restore it. A place is never deleted: the markets that measure it keep their history. Restoring takes a slot of the plan's cap.","operationId":"update_location_v1_brands__brand_id__locations__location_id__patch","parameters":[{"name":"location_id","in":"path","required":true,"schema":{"type":"string","description":"Place UUID.","title":"Location Id"},"description":"Place UUID."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationUpdate"}}}},"responses":{"200":{"description":"Updated or archive a place","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Location"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:locations","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/locations/imports":{"post":{"tags":["Locations"],"summary":"Import places","description":"Import places from the brand's linked Google Business Profile locations (`source: gbp`, every one or `gbp_location_ids`) or from a CSV with a header row (`source: csv`: name, address, city, region, country, postal_code, phone, website, latitude, longitude, external_ref). A place already there comes back as it is.","operationId":"import_locations_v1_brands__brand_id__locations_imports_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationImport"}}}},"responses":{"201":{"description":"Import places","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationImported"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:locations","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/locations/{location_id}/directory-listings":{"get":{"tags":["Locations"],"summary":"List a place's local sources","description":"The directories the place should be listed on (by its country and kind of business: Yelp, Foursquare, Avvo, Healthgrades, Gelbe Seiten...) and whether it is on each: `listed` with the listing, `missing` or `unknown`. Read free from the brand's AI citations and the last checks; `next_check` says what a check would search and cost now. Presence only, no reviews. Not paginated: a place has a few dozen directories at most.","operationId":"list_directory_listings_v1_brands__brand_id__locations__location_id__directory_listings_get","parameters":[{"name":"location_id","in":"path","required":true,"schema":{"type":"string","description":"Place UUID.","title":"Location Id"},"description":"Place UUID."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned a place's local sources","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlaceDirectories"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:locations","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/locations/{location_id}/directory-checks":{"post":{"tags":["Locations"],"summary":"Check a place's listings","description":"Search the place's directories for its listing (a Google site: search, or Tripadvisor's own search): one credit per 10 directories searched, and what the searches that do not answer added is refunded. Directories the brand's citations already show listed, set by hand, or checked in the last week are skipped unless named in `directories`; nothing to search charges nothing. Results land within minutes: read the listings again (`check.status`). One check per place at a time (`409 conflict`). Nothing is published to any directory.","operationId":"create_directory_check_v1_brands__brand_id__locations__location_id__directory_checks_post","parameters":[{"name":"location_id","in":"path","required":true,"schema":{"type":"string","description":"Place UUID.","title":"Location Id"},"description":"Place UUID."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/DirectoryCheckCreate"},{"type":"null"}],"title":"Payload"}}}},"responses":{"202":{"description":"Check a place's listings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DirectoryCheckQueued"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"402":{"description":"Not enough credits to complete this operation","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"insufficient_credits","message":"Not enough credits to complete this operation"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:locations","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/locations/{location_id}/geo-scans":{"post":{"tags":["Local rank"],"summary":"Scan a place on the map","description":"Rank the place in Google Maps' local pack at every point of a grid around it, one scan per search in `keywords` (up to 10), all sharing a `run_id`. `grid_size` is 3, 5, 7 and `spacing_km` the distance between points (up to 20), or `auto`, the default, to set it off the centre's own results (the first search's centre is read first; every search of the run takes that spacing). The grid is centred on the place's pin (found on Google Maps by its name and city on the first scan when the place has none), or on `center_lat` and `center_lng` when given. No Google connection is needed. Answers the pending scans at once; read each with `GET .../geo-scans/{scan_id}` until `status` is `completed` or `failed`. Each scan costs one credit per 16 points, rounded up (a 3x3 grid 1, 5x5 2, 7x7 4), reserved when it starts and refunded if it fails; charged to the brand owner. `?dry_run=true` answers the total. An archived place answers `400 validation_error`. Requires the brand owner on Starter or with an active API subscription: `403 brand_plan_required` otherwise.","operationId":"run_place_geo_scans_v1_brands__brand_id__locations__location_id__geo_scans_post","parameters":[{"name":"location_id","in":"path","required":true,"schema":{"type":"string","description":"The place's id, from `GET /v1/brands/{brand_id}/locations`.","title":"Location Id"},"description":"The place's id, from `GET /v1/brands/{brand_id}/locations`."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlaceGeoScanCreate"}}}},"responses":{"202":{"description":"Scan a place on the map","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlaceGeoScanRun"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"402":{"description":"Not enough credits to complete this operation","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"insufficient_credits","message":"Not enough credits to complete this operation"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:locations","x-rankprompt-cost":{"request_units":1,"credits":0}},"get":{"tags":["Local rank"],"summary":"List a place's scans","description":"The place's geo-grid scans, newest first, without their points (older scans of its linked Google location included). `keyword` keeps one search, case ignored. Cursor paginated via `limit` and `cursor`.","operationId":"list_place_geo_scans_v1_brands__brand_id__locations__location_id__geo_scans_get","parameters":[{"name":"location_id","in":"path","required":true,"schema":{"type":"string","description":"The place's id, from `GET /v1/brands/{brand_id}/locations`.","title":"Location Id"},"description":"The place's id, from `GET /v1/brands/{brand_id}/locations`."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"keyword","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}],"description":"Only this search (case ignored).","title":"Keyword"},"description":"Only this search (case ignored)."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Page size (default 20, max 100).","default":20,"title":"Limit"},"description":"Page size (default 20, max 100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Continuation token from a previous response's `next_cursor`.","title":"Cursor"},"description":"Continuation token from a previous response's `next_cursor`."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned a place's scans","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlaceGeoScanList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:locations","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/locations/{location_id}/local-scans":{"post":{"tags":["Local rank"],"summary":"Run a local scan on a place","description":"Scan the place in one run on one grid: where it ranks in Google Maps' local pack for each search in `searches` (up to 10, one scan each), and whether Gemini, with Google Search and Google Maps grounding at each point, names it for each question in `prompts` (up to 5). A question must not name the place's city (`near me` is fine): one that does answers `400 validation_error`. `grid_size` is 3, 5, 7 and `spacing_km` up to 20 or `auto`, the default (set off the first search's centre, read first); the grid is centred on the place's pin or on `center_lat` and `center_lng`. Costs one credit per 3 AI answers (points times questions), rounded up, the Maps searches included; reserved at the start, the answers that fail are refunded when the AI grid settles. Charged to the brand owner; `?dry_run=true` answers the total. Answers the pending Maps scans and AI grid, which share `run_id`; read them with `GET .../geo-scans/{scan_id}` and `GET .../ai-geo-scans/{scan_id}` until `status` is `completed` or `failed`. When the AI grid cannot be queued it is refunded at once, `ai_scan.status` is `failed` and no Maps scan starts (`data` is empty). Requires the brand owner on Starter or with an active API subscription: `403 brand_plan_required` otherwise.","operationId":"run_local_scan_v1_brands__brand_id__locations__location_id__local_scans_post","parameters":[{"name":"location_id","in":"path","required":true,"schema":{"type":"string","description":"The place's id, from `GET /v1/brands/{brand_id}/locations`.","title":"Location Id"},"description":"The place's id, from `GET /v1/brands/{brand_id}/locations`."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocalScanCreate"}}}},"responses":{"202":{"description":"Run a local scan on a place","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocalScanRun"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"402":{"description":"Not enough credits to complete this operation","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"insufficient_credits","message":"Not enough credits to complete this operation"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:locations","x-rankprompt-cost":{"request_units":1,"credits":0},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}},"get":{"tags":["Local rank"],"summary":"List a place's local scan runs","description":"The place's runs, newest first: each with its Maps scans (one per search, without points) and its AI grid (without points), the grid and the schedule that ran it. A scan that ran alone, before runs or as an AI grid by itself, is a run of its own. Read a scan's points with `GET .../geo-scans/{scan_id}` and the AI grid's with `GET .../ai-geo-scans/{scan_id}`. Cursor paginated via `limit` and `cursor`.","operationId":"list_local_scans_v1_brands__brand_id__locations__location_id__local_scans_get","parameters":[{"name":"location_id","in":"path","required":true,"schema":{"type":"string","description":"The place's id, from `GET /v1/brands/{brand_id}/locations`.","title":"Location Id"},"description":"The place's id, from `GET /v1/brands/{brand_id}/locations`."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Page size (default 20, max 100).","default":20,"title":"Limit"},"description":"Page size (default 20, max 100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Continuation token from a previous response's `next_cursor`.","title":"Cursor"},"description":"Continuation token from a previous response's `next_cursor`."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned a place's local scan runs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocalScanRunList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:locations","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/locations/{location_id}/geo-scans/{scan_id}":{"get":{"tags":["Local rank"],"summary":"Retrieve a place's scan","description":"One scan with every point of its grid: the place's rank there (null when it is not in the local pack) and the businesses of the local pack. A scan of another place or brand answers `404 not_found`.","operationId":"get_place_geo_scan_v1_brands__brand_id__locations__location_id__geo_scans__scan_id__get","parameters":[{"name":"location_id","in":"path","required":true,"schema":{"type":"string","description":"The place's id, from `GET /v1/brands/{brand_id}/locations`.","title":"Location Id"},"description":"The place's id, from `GET /v1/brands/{brand_id}/locations`."},{"name":"scan_id","in":"path","required":true,"schema":{"type":"string","description":"A scan's id, from `GET .../geo-scans`.","title":"Scan Id"},"description":"A scan's id, from `GET .../geo-scans`."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned a place's scan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlaceGeoScan"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:locations","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/locations/{location_id}/geo-scan-keywords":{"get":{"tags":["Local rank"],"summary":"List a place's scanned searches","description":"Every search the place has completed scans of, newest first: its newest scan's mean rank, points found and share of top 3 points, and the same figures of the scan before it.","operationId":"list_place_geo_scan_keywords_v1_brands__brand_id__locations__location_id__geo_scan_keywords_get","parameters":[{"name":"location_id","in":"path","required":true,"schema":{"type":"string","description":"The place's id, from `GET /v1/brands/{brand_id}/locations`.","title":"Location Id"},"description":"The place's id, from `GET /v1/brands/{brand_id}/locations`."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned a place's scanned searches","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoScanKeywordList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:locations","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/locations/{location_id}/geo-scan-trends":{"get":{"tags":["Local rank"],"summary":"A search's trend at a place","description":"One search's completed scans of the place between `since` and `until` (default the last 180 days, at most 400), oldest first: each scan's mean rank, points found and share of top 3 points; `ai` adds the place's AI grids of the window with the share of their answers naming the brand.","operationId":"get_place_geo_scan_trend_v1_brands__brand_id__locations__location_id__geo_scan_trends_get","parameters":[{"name":"location_id","in":"path","required":true,"schema":{"type":"string","description":"The place's id, from `GET /v1/brands/{brand_id}/locations`.","title":"Location Id"},"description":"The place's id, from `GET /v1/brands/{brand_id}/locations`."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"keyword","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":120,"description":"The search, case ignored.","title":"Keyword"},"description":"The search, case ignored."},{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Start of the window (ISO 8601).","title":"Since"},"description":"Start of the window (ISO 8601)."},{"name":"until","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"End of the window (ISO 8601), default now.","title":"Until"},"description":"End of the window (ISO 8601), default now."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"A search's trend at a place","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoScanTrend"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:locations","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/locations/{location_id}/geo-scan-comparisons":{"get":{"tags":["Local rank"],"summary":"Compare two scans of a place","description":"Two completed scans of the place side by side, the older one first: the change in mean rank (positive is worse), share of top 3 points and points found, and, when both used the same grid around the same centre, each point's rank in both. When both scans' runs have a completed AI grid, `ai` compares them the same way (the share of answers naming the brand, overall and point by point); `ai_grids` names each run's AI grid and its share either way, null for a run without one.","operationId":"compare_place_geo_scans_v1_brands__brand_id__locations__location_id__geo_scan_comparisons_get","parameters":[{"name":"location_id","in":"path","required":true,"schema":{"type":"string","description":"The place's id, from `GET /v1/brands/{brand_id}/locations`.","title":"Location Id"},"description":"The place's id, from `GET /v1/brands/{brand_id}/locations`."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"from_scan_id","in":"query","required":true,"schema":{"type":"string","description":"One scan's id.","title":"From Scan Id"},"description":"One scan's id."},{"name":"to_scan_id","in":"query","required":true,"schema":{"type":"string","description":"The other scan's id.","title":"To Scan Id"},"description":"The other scan's id."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Compare two scans of a place","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoScanComparison"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:locations","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/locations/{location_id}/ai-geo-scans":{"post":{"tags":["Local rank"],"summary":"Run an AI grid on a place","description":"Ask Gemini each prompt in `prompts` (up to 5) at every point of a grid around the place, with Google Search and Google Maps grounding at the point's coordinates: which businesses AI recommends there and whether the brand is one. No other engine is asked: inside a city only Gemini with Google Maps changes with the point above its own noise. A prompt must not name the place's city or region (`near me` is fine): one that does answers `400 validation_error`. `grid_size` is 3, 5, 7 and `spacing_km` up to 20; the grid is centred on the place's pin or on `center_lat` and `center_lng`. Costs one credit per 3 cells (points times prompts), rounded up, reserved at the start; the cells that fail are refunded when the scan settles. Charged to the brand owner; `?dry_run=true` answers the total. Answers the pending scan with its points; read it until `status` is `completed` or `failed`. Requires the brand owner on Starter or with an active API subscription: `403 brand_plan_required` otherwise.","operationId":"run_ai_geo_scan_v1_brands__brand_id__locations__location_id__ai_geo_scans_post","parameters":[{"name":"location_id","in":"path","required":true,"schema":{"type":"string","description":"The place's id, from `GET /v1/brands/{brand_id}/locations`.","title":"Location Id"},"description":"The place's id, from `GET /v1/brands/{brand_id}/locations`."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiGeoScanCreate"}}}},"responses":{"202":{"description":"Run an AI grid on a place","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiGeoScan"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"402":{"description":"Not enough credits to complete this operation","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"insufficient_credits","message":"Not enough credits to complete this operation"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:locations","x-rankprompt-cost":{"request_units":1,"credits":0},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}},"get":{"tags":["Local rank"],"summary":"List a place's AI grids","description":"The place's AI grid scans, newest first, without their points. Cursor paginated via `limit` and `cursor`.","operationId":"list_ai_geo_scans_v1_brands__brand_id__locations__location_id__ai_geo_scans_get","parameters":[{"name":"location_id","in":"path","required":true,"schema":{"type":"string","description":"The place's id, from `GET /v1/brands/{brand_id}/locations`.","title":"Location Id"},"description":"The place's id, from `GET /v1/brands/{brand_id}/locations`."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Page size (default 20, max 100).","default":20,"title":"Limit"},"description":"Page size (default 20, max 100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Continuation token from a previous response's `next_cursor`.","title":"Cursor"},"description":"Continuation token from a previous response's `next_cursor`."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned a place's AI grids","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiGeoScanList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:locations","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/locations/{location_id}/ai-geo-scans/{scan_id}":{"get":{"tags":["Local rank"],"summary":"Retrieve an AI grid","description":"One AI grid scan with every point: the share of its answered prompts that name the brand. A scan of another place or brand answers `404 not_found`.","operationId":"get_ai_geo_scan_v1_brands__brand_id__locations__location_id__ai_geo_scans__scan_id__get","parameters":[{"name":"location_id","in":"path","required":true,"schema":{"type":"string","description":"The place's id, from `GET /v1/brands/{brand_id}/locations`.","title":"Location Id"},"description":"The place's id, from `GET /v1/brands/{brand_id}/locations`."},{"name":"scan_id","in":"path","required":true,"schema":{"type":"string","description":"An AI grid scan's id, from `GET .../ai-geo-scans`.","title":"Scan Id"},"description":"An AI grid scan's id, from `GET .../ai-geo-scans`."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned an AI grid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiGeoScan"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:locations","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/locations/{location_id}/ai-geo-scans/{scan_id}/businesses":{"get":{"tags":["Local rank"],"summary":"List the businesses an AI grid named","description":"The businesses the scan's answers named most (up to 20): in how many answers and points, their average position and how often first. The brand's own place has `is_brand` true.","operationId":"list_ai_geo_scan_businesses_v1_brands__brand_id__locations__location_id__ai_geo_scans__scan_id__businesses_get","parameters":[{"name":"location_id","in":"path","required":true,"schema":{"type":"string","description":"The place's id, from `GET /v1/brands/{brand_id}/locations`.","title":"Location Id"},"description":"The place's id, from `GET /v1/brands/{brand_id}/locations`."},{"name":"scan_id","in":"path","required":true,"schema":{"type":"string","description":"An AI grid scan's id, from `GET .../ai-geo-scans`.","title":"Scan Id"},"description":"An AI grid scan's id, from `GET .../ai-geo-scans`."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned the businesses an AI grid named","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiGeoScanBusinessList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:locations","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/locations/{location_id}/ai-geo-scans/{scan_id}/points/{point_id}":{"get":{"tags":["Local rank"],"summary":"Retrieve a point of an AI grid","description":"Every prompt's answer at the point (the businesses Gemini named, in order, and its sources) and the Google Maps local pack at the nearest point of the place's Maps scan: the one `geo_scan_id` names, else its newest completed one. `local_pack` is null when no Maps point lies near this one.","operationId":"get_ai_geo_scan_point_v1_brands__brand_id__locations__location_id__ai_geo_scans__scan_id__points__point_id__get","parameters":[{"name":"location_id","in":"path","required":true,"schema":{"type":"string","description":"The place's id, from `GET /v1/brands/{brand_id}/locations`.","title":"Location Id"},"description":"The place's id, from `GET /v1/brands/{brand_id}/locations`."},{"name":"scan_id","in":"path","required":true,"schema":{"type":"string","description":"An AI grid scan's id, from `GET .../ai-geo-scans`.","title":"Scan Id"},"description":"An AI grid scan's id, from `GET .../ai-geo-scans`."},{"name":"point_id","in":"path","required":true,"schema":{"type":"string","description":"A point's id, from the scan's `points`.","title":"Point Id"},"description":"A point's id, from the scan's `points`."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"geo_scan_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The Maps scan to compare with, from `GET .../geo-scans`.","title":"Geo Scan Id"},"description":"The Maps scan to compare with, from `GET .../geo-scans`."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned a point of an AI grid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiGeoPoint"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:locations","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/local-scan-schedules":{"get":{"tags":["Local rank"],"summary":"List map scan schedules","description":"The brand's scheduled place scans, newest first; `location_id` keeps one place. Cursor paginated.","operationId":"list_local_scan_schedules_v1_brands__brand_id__local_scan_schedules_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"location_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only this place's schedules.","title":"Location Id"},"description":"Only this place's schedules."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Page size (default 20, max 100).","default":20,"title":"Limit"},"description":"Page size (default 20, max 100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Continuation token from a previous response's `next_cursor`.","title":"Cursor"},"description":"Continuation token from a previous response's `next_cursor`."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned map scan schedules","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocalScanScheduleList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:locations","x-rankprompt-cost":{"request_units":1,"credits":0}},"post":{"tags":["Local rank"],"summary":"Schedule a place's map scans","description":"Scan a place for up to 10 searches on one grid, `daily`, `weekly` or `monthly` (`off` keeps it saved and stopped); the first run lands within the hour. `prompts` (up to 5 questions, none naming the city) makes each run ask Gemini with Google Maps too, as `POST .../local-scans` does. Each run costs `credits_per_run` (without `prompts`, one scan per search: Each scan costs one credit per 16 points, rounded up (a 3x3 grid 1, 5x5 2, 7x7 4), reserved when it starts and refunded if it fails; charged to the brand owner. With `prompts`, one credit per 3 AI answers (points times questions), rounded up, the Maps searches included.) A run that finds too few credits pauses the schedule. `alert_rank_drop` (positions, default 3) and `alert_top3_drop` (percentage points, default 20) tell the brand owner, and send the `local_rank.dropped` webhook, when a run worsens a search past them against the run before; null turns one off. Requires the brand owner on Starter or with an active API subscription: `403 brand_plan_required` otherwise.","operationId":"create_local_scan_schedule_v1_brands__brand_id__local_scan_schedules_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocalScanScheduleCreate"}}}},"responses":{"201":{"description":"Schedule a place's map scans","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocalScanSchedule"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:locations","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/local-scan-schedules/{schedule_id}":{"get":{"tags":["Local rank"],"summary":"Retrieve a map scan schedule","description":"One schedule with its next run and what a run costs.","operationId":"get_local_scan_schedule_v1_brands__brand_id__local_scan_schedules__schedule_id__get","parameters":[{"name":"schedule_id","in":"path","required":true,"schema":{"type":"string","description":"A schedule's id.","title":"Schedule Id"},"description":"A schedule's id."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned a map scan schedule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocalScanSchedule"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:locations","x-rankprompt-cost":{"request_units":1,"credits":0}},"patch":{"tags":["Local rank"],"summary":"Update a map scan schedule","description":"Change the searches, the questions (`[]` goes back to Maps only), the grid, the centre, the frequency or the alerts; only the fields sent change. Saving resumes a paused schedule. Requires the brand owner on Starter or with an active API subscription: `403 brand_plan_required` otherwise.","operationId":"update_local_scan_schedule_v1_brands__brand_id__local_scan_schedules__schedule_id__patch","parameters":[{"name":"schedule_id","in":"path","required":true,"schema":{"type":"string","description":"A schedule's id.","title":"Schedule Id"},"description":"A schedule's id."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocalScanScheduleUpdate"}}}},"responses":{"200":{"description":"Updated a map scan schedule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocalScanSchedule"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:locations","x-rankprompt-cost":{"request_units":1,"credits":0}},"delete":{"tags":["Local rank"],"summary":"Delete a map scan schedule","description":"Delete the schedule; the scans it ran stay in the place's history.","operationId":"delete_local_scan_schedule_v1_brands__brand_id__local_scan_schedules__schedule_id__delete","parameters":[{"name":"schedule_id","in":"path","required":true,"schema":{"type":"string","description":"A schedule's id.","title":"Schedule Id"},"description":"A schedule's id."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"204":{"description":"Deleted a map scan schedule","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:locations","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/local-scan-schedules/{schedule_id}/runs":{"post":{"tags":["Local rank"],"summary":"Run a map scan schedule now","description":"Run the schedule now, as one of its runs (its alerts compare it like any run): every search, and the AI grid of its `prompts` when it has any. Each scan costs one credit per 16 points, rounded up (a 3x3 grid 1, 5x5 2, 7x7 4), reserved when it starts and refunded if it fails; charged to the brand owner. With `prompts`, the run costs one credit per 3 AI answers (points times questions), rounded up, the Maps searches included. `?dry_run=true` answers the total. Requires the brand owner on Starter or with an active API subscription: `403 brand_plan_required` otherwise.","operationId":"run_local_scan_schedule_v1_brands__brand_id__local_scan_schedules__schedule_id__runs_post","parameters":[{"name":"schedule_id","in":"path","required":true,"schema":{"type":"string","description":"A schedule's id.","title":"Schedule Id"},"description":"A schedule's id."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"202":{"description":"Run a map scan schedule now","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlaceGeoScanRun"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"402":{"description":"Not enough credits to complete this operation","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"insufficient_credits","message":"Not enough credits to complete this operation"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:locations","x-rankprompt-cost":{"request_units":1,"credits":0},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}}},"/v1/reports/{report_id}/markets":{"get":{"tags":["Reports"],"summary":"List a report's markets","description":"Where a report asks its prompts, oldest first: each run leaves one report per active market. `report_id` is the report's id or any of its runs' reports; the markets of a scheduled report are its region configs. `include_archived` adds archived ones.","operationId":"list_markets_v1_reports__report_id__markets_get","parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"string","description":"Report UUID.","title":"Report Id"},"description":"Report UUID."},{"name":"include_archived","in":"query","required":false,"schema":{"type":"boolean","description":"`true` adds archived markets.","default":false,"title":"Include Archived"},"description":"`true` adds archived markets."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned a report's markets","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:markets","x-rankprompt-cost":{"request_units":1,"credits":0}},"post":{"tags":["Reports"],"summary":"Add markets to a report","description":"Add markets (a country, a city in it, or one of the brand's places with `location_id`); each asks the report's prompts from its next run, and each active market is charged on every run. A city takes its `region` and centre (`latitude`, `longitude`); without a centre one Google lists is placed in the background. A city sent without its `region` whose name the country shares (`Emerald` in Australia) comes back with `measured_as`, the town it is measured as, and `namesake_regions`, where the others are: set `region` if another was meant. A place and language the report measures already comes back as it is (resumed when paused). The brand owner's plan caps the active markets of a report (`402 insufficient_credits` with `details.reason` `plan_limit`).","operationId":"add_markets_v1_reports__report_id__markets_post","parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"string","description":"Report UUID.","title":"Report Id"},"description":"Report UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketCreate"}}}},"responses":{"201":{"description":"Add markets to a report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:markets","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/reports/{report_id}/markets/{market_id}":{"patch":{"tags":["Reports"],"summary":"Update a report's market","description":"Change a market's label, what `{city}` becomes in its prompts, its language or AI platforms, its city's `region` and centre (`latitude`, `longitude`), link one of the brand's places (`location_id`), or pause, resume or archive it (`status`). A market is never deleted: its results stay.","operationId":"update_market_v1_reports__report_id__markets__market_id__patch","parameters":[{"name":"market_id","in":"path","required":true,"schema":{"type":"string","description":"Market UUID.","title":"Market Id"},"description":"Market UUID."},{"name":"report_id","in":"path","required":true,"schema":{"type":"string","description":"Report UUID.","title":"Report Id"},"description":"Report UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketUpdate"}}}},"responses":{"200":{"description":"Updated a report's market","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Market"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:markets","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/scheduled-reports":{"get":{"tags":["Scheduled reports"],"summary":"List scheduled reports","description":"List scheduled reports under a brand (newest first). Cursor-paginated.\n\nThe `brand_id` query parameter is **required**.\n\nFilters compose with AND: `is_active`, `frequency`, and `search` (case-insensitive substring on `name`, or on a region config's city, country or name).","operationId":"list_scheduled_reports_v1_scheduled_reports_get","parameters":[{"name":"is_active","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Optional: filter by active state.","title":"Is Active"},"description":"Optional: filter by active state."},{"name":"frequency","in":"query","required":false,"schema":{"anyOf":[{"enum":["daily","weekly","monthly"],"type":"string"},{"type":"null"}],"description":"Optional: filter by cadence.","title":"Frequency"},"description":"Optional: filter by cadence."},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Case-insensitive substring match on `name` or on a region config's place.","title":"Search"},"description":"Case-insensitive substring match on `name` or on a region config's place."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Page size (default 20, max 100).","default":20,"title":"Limit"},"description":"Page size (default 20, max 100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Continuation token from a previous response's `next_cursor`.","title":"Cursor"},"description":"Continuation token from a previous response's `next_cursor`."},{"name":"brand_id","in":"query","required":true,"schema":{"type":"string","description":"Brand UUID to scope the listing. **Required.**","examples":["b3d2c1a0-1234-4abc-9def-0123456789ab"],"title":"Brand Id"},"description":"Brand UUID to scope the listing. **Required.**"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned scheduled reports","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduledReportList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:scheduled","x-rankprompt-cost":{"request_units":1,"credits":0}},"post":{"tags":["Scheduled reports"],"summary":"Create a scheduled report","description":"Create a scheduled report. `next_run_at` is the next occurrence of its `schedule` slot: pass one, or it runs at the time of day it was created (UTC), one `frequency` from now.\n\nThe fastest setup passes `region_configs`: every market (country, optional city, language) with its prompts, created in the same call, all or nothing. The schedule is active as soon as one of them has prompts, and every run leaves one report per active region config.\n\nWithout `region_configs` the schedule starts **inactive** (`is_active: false`, `paused_reason: no_markets`): one with no region configs produces no reports. It activates by itself as soon as you add the first active region config in step 2: complete the steps below and no extra call is needed. A schedule left without one never runs and never bills.\n\nStep by step instead:\n1. `POST /v1/scheduled-reports` (this endpoint).\n2. For each region you want to track: `POST /v1/region-configs` with `scheduled_report_id` set (up to the brand owner's plan cap of region configs per report).\n3. Seed each config's prompts: `POST /v1/region-configs/{config_id}/prompts`.\n\nEvery tick (or manual `POST .../executions`) materialises one report per active region config of the schedule.\n\nClient delivery (Agency): set `deliver_to_client` to email a branded PDF report to the client after every completed run. New schedules hold each report for approval in the app (`require_review: true`); pass `require_review: false` to send automatically.","operationId":"create_scheduled_report_v1_scheduled_reports_post","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduledReportCreate"}}}},"responses":{"201":{"description":"Schedule created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduledReport"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:scheduled","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/scheduled-reports/{scheduled_report_id}":{"get":{"tags":["Scheduled reports"],"summary":"Retrieve a scheduled report","description":"Return a single scheduled report by id, including its `frequency`, `next_run_at`, its `schedule` slot and `is_active` state. Region configs and runs are available via the sub-resources.","operationId":"get_scheduled_report_v1_scheduled_reports__scheduled_report_id__get","parameters":[{"name":"scheduled_report_id","in":"path","required":true,"schema":{"type":"string","description":"Scheduled report UUID.","title":"Scheduled Report Id"},"description":"Scheduled report UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned a scheduled report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduledReport"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:scheduled","x-rankprompt-cost":{"request_units":1,"credits":0}},"patch":{"tags":["Scheduled reports"],"summary":"Update a scheduled report","description":"Partial update of a scheduled report. Mutable fields: `name`, `frequency`, `is_active`, `next_run_at`, `schedule`, and the client delivery fields (`deliver_to_client`, `recipient_emails`, `cc_self`, `client_intro_message`, `template_key`, `account_template_id`, `require_review`).\n\n`next_run_at` always follows the schedule's slot: changing `frequency` moves it to the slot's next occurrence, and a `next_run_at` you set moves the slot to its time of day (and weekday or day of month). `deliver_to_client: false` turns client delivery off and drops its settings.","operationId":"update_scheduled_report_v1_scheduled_reports__scheduled_report_id__patch","parameters":[{"name":"scheduled_report_id","in":"path","required":true,"schema":{"type":"string","description":"Scheduled report UUID.","title":"Scheduled Report Id"},"description":"Scheduled report UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduledReportUpdate"}}}},"responses":{"200":{"description":"Updated a scheduled report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduledReport"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:scheduled","x-rankprompt-cost":{"request_units":1,"credits":0}},"delete":{"tags":["Scheduled reports"],"summary":"Delete a scheduled report","description":"Delete a scheduled report and its full run history: it is gone at once, and its reports, their prompts and its region configs are removed in the background.\n\nRefused with `400 validation_error` while a run is processing. Irreversible. Requires OWNER access on the brand.","operationId":"delete_scheduled_report_v1_scheduled_reports__scheduled_report_id__delete","parameters":[{"name":"scheduled_report_id","in":"path","required":true,"schema":{"type":"string","description":"Scheduled report UUID.","title":"Scheduled Report Id"},"description":"Scheduled report UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"204":{"description":"Schedule deleted.","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:scheduled","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/scheduled-reports/{scheduled_report_id}/duplicates":{"post":{"tags":["Scheduled reports"],"summary":"Duplicate a scheduled report","description":"Create a new scheduled report from an existing one, with the `name` and `frequency` given: the source's client delivery settings, every region config (country, city, language, AI platforms, active state) and its active prompts are copied. Past runs are not. All or nothing. A copy of a paused schedule stays paused, and copying client delivery needs the owner on Agency, as on create.\n\nThe copy's `next_run_at` is the next occurrence of its `schedule` slot (or one `frequency` from now). Use it to track the same markets on another cadence, or as the starting point for a new set of markets.\n\nWith `target_brand_id` the copy goes into another brand you edit, under that brand's owner's plan caps: the source brand's name and aliases in the prompts become the target's name, a market on one of the source's places becomes a plain city market, and client delivery stays behind. A brand you cannot edit answers `404`.","operationId":"duplicate_scheduled_report_v1_scheduled_reports__scheduled_report_id__duplicates_post","parameters":[{"name":"scheduled_report_id","in":"path","required":true,"schema":{"type":"string","description":"Scheduled report UUID.","title":"Scheduled Report Id"},"description":"Scheduled report UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduledReportDuplicate"}}}},"responses":{"201":{"description":"Schedule duplicated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduledReport"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:scheduled","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/scheduled-reports/{scheduled_report_id}/runs":{"get":{"tags":["Scheduled reports"],"summary":"List schedule runs","description":"The schedule's runs, newest first. A run groups the reports it left, one per region config, so a schedule with three markets shows three reports under each run.\n\nOffset paginated via `limit` (1-100, default 20) and `offset`.","operationId":"list_schedule_runs_v1_scheduled_reports__scheduled_report_id__runs_get","parameters":[{"name":"scheduled_report_id","in":"path","required":true,"schema":{"type":"string","description":"Scheduled report UUID.","title":"Scheduled Report Id"},"description":"Scheduled report UUID."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Runs per page (1-100, default 20).","default":20,"title":"Limit"},"description":"Runs per page (1-100, default 20)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Runs to skip from the newest.","default":0,"title":"Offset"},"description":"Runs to skip from the newest."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned schedule runs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduleRunList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:scheduled","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/scheduled-reports/{scheduled_report_id}/executions":{"post":{"tags":["Scheduled reports"],"summary":"Run schedule now","description":"Dispatch a manual execution of the schedule, outside its normal cadence. Returns `202 Accepted` with a `job_id` you can poll via `GET /v1/jobs/{job_id}`, the `run_id` and the `report_ids` it builds.\n\nBy default the run covers every active region config of the schedule. Pass `region_config_id` in the body to scope the run to a single region.\n\nManual runs do not advance `next_run_at`. A run already processing answers `409 report_not_modifiable`; the call's `Idempotency-Key` also keys the run.\n\nRequires the brand to have facts set (`brand_info.description` non-empty). Returns `422 brand_facts_required` otherwise; populate facts via `POST` or `PATCH /v1/brands/{brand_id}/facts`.\n\nRate limited more tightly than most endpoints; the exact limit is published as `x-rankprompt-rate-limit` on this operation. See `429 rate_limit_exceeded` response.","operationId":"trigger_schedule_run_v1_scheduled_reports__scheduled_report_id__executions_post","parameters":[{"name":"scheduled_report_id","in":"path","required":true,"schema":{"type":"string","description":"Scheduled report UUID.","title":"Scheduled Report Id"},"description":"Scheduled report UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduledReportRun","default":{}}}}},"responses":{"202":{"description":"Manual run dispatched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduledReportRunDispatched"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"402":{"description":"Not enough credits to complete this operation","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"insufficient_credits","message":"Not enough credits to complete this operation"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:scheduled","x-rankprompt-cost":{"request_units":5,"credits":0},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}}},"/v1/scheduled-reports/{scheduled_report_id}/region-configs":{"get":{"tags":["Scheduled reports"],"summary":"List attached region configs","description":"Return every region config of this schedule (newest first), active and paused, in one unpaginated response.","operationId":"list_schedule_region_configs_v1_scheduled_reports__scheduled_report_id__region_configs_get","parameters":[{"name":"scheduled_report_id","in":"path","required":true,"schema":{"type":"string","description":"Scheduled report UUID.","title":"Scheduled Report Id"},"description":"Scheduled report UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned attached region configs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduleRegionConfigList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:scheduled","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/scheduled-reports/{scheduled_report_id}/region-configs/{region_config_id}":{"post":{"tags":["Scheduled reports"],"summary":"Attach a region config","description":"A region config belongs to the schedule it was created for (`POST /v1/region-configs` with `scheduled_report_id`). This answers the config when it is already this schedule's, and returns `400 validation_error` when it belongs to another schedule: create another region config for this one.\n\nTo remove a region from a schedule, delete the region config itself (`DELETE /v1/region-configs/{id}`).","operationId":"attach_region_config_v1_scheduled_reports__scheduled_report_id__region_configs__region_config_id__post","parameters":[{"name":"region_config_id","in":"path","required":true,"schema":{"type":"string","description":"Region config UUID.","title":"Region Config Id"},"description":"Region config UUID."},{"name":"scheduled_report_id","in":"path","required":true,"schema":{"type":"string","description":"Scheduled report UUID.","title":"Scheduled Report Id"},"description":"Scheduled report UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Region config already attached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegionConfig"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:scheduled","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/scheduled-reports/{scheduled_report_id}/analytics":{"get":{"tags":["Scheduled reports"],"summary":"Schedule analytics","description":"Aggregated metrics across every completed run of the schedule:\n\n- `avg_visibility`: answers naming the brand over every answer of every run.\n- `prompts[*]`: per-prompt sparklines and totals, one row per prompt and region config; `trend_delta` compares the newer half of the runs with the older half.\n- `platform_performance[*]`: appearance rate per AI platform.\n- `regions[*]`: per region config, its visibility in every completed run and its own `platform_performance`, to read one location the way the Overview's location filter does. The prompts of a location are the `prompts[*]` with its `region_config_id`.\n\n`date_from` and `date_to` keep the runs started in that period; every metric, the halves `trend_delta` compares included, is then computed over those runs only. Without them it reflects every run available at request time.","operationId":"get_schedule_analytics_v1_scheduled_reports__scheduled_report_id__analytics_get","parameters":[{"name":"scheduled_report_id","in":"path","required":true,"schema":{"type":"string","description":"Scheduled report UUID.","title":"Scheduled Report Id"},"description":"Scheduled report UUID."},{"name":"date_from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only runs started at or after this time, inclusive (ISO-8601).","title":"Date From"},"description":"Only runs started at or after this time, inclusive (ISO-8601)."},{"name":"date_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only runs started before this time, exclusive (ISO-8601); not before `date_from`.","title":"Date To"},"description":"Only runs started before this time, exclusive (ISO-8601); not before `date_from`."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Schedule analytics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduleAnalytics"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:scheduled","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/scheduled-reports/{scheduled_report_id}/prompt-history/{region_config_prompt_id}":{"get":{"tags":["Scheduled reports"],"summary":"Prompt run history","description":"Run history for a single region-config prompt across the completed runs of the schedule, newest first, a page at a time. One entry per region config and run that got answers, with the per-AI-platform breakdown inlined (a prompt every region config shares has one entry per region config).\n\nUseful for charting how a specific prompt's visibility evolves over time.","operationId":"get_schedule_prompt_history_v1_scheduled_reports__scheduled_report_id__prompt_history__region_config_prompt_id__get","parameters":[{"name":"region_config_prompt_id","in":"path","required":true,"schema":{"type":"string","description":"Region config prompt UUID.","title":"Region Config Prompt Id"},"description":"Region config prompt UUID."},{"name":"scheduled_report_id","in":"path","required":true,"schema":{"type":"string","description":"Scheduled report UUID.","title":"Scheduled Report Id"},"description":"Scheduled report UUID."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Page size (default 20, max 100).","default":20,"title":"Limit"},"description":"Page size (default 20, max 100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Continuation token from a previous response's `next_cursor`.","title":"Cursor"},"description":"Continuation token from a previous response's `next_cursor`."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Prompt run history","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulePromptHistory"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:scheduled","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/scheduled-reports/{scheduled_report_id}/shares":{"get":{"tags":["Shares"],"summary":"List scheduled-report shares","description":"List the caller's non-expired public share links for a scheduled report (newest first).\n\nOnly shares created by the authenticated principal are returned: shares created by other teammates are not visible.","operationId":"list_scheduled_shares_v1_scheduled_reports__scheduled_report_id__shares_get","parameters":[{"name":"scheduled_report_id","in":"path","required":true,"schema":{"type":"string","description":"Scheduled report UUID.","title":"Scheduled Report Id"},"description":"Scheduled report UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned scheduled-report shares","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduledReportShareList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:scheduled","x-rankprompt-cost":{"request_units":1,"credits":0}},"post":{"tags":["Shares"],"summary":"Create a scheduled-report share","description":"Create a public share link to the aggregated snapshot of a scheduled report (rolls up every completed run on the schedule).\n\nIf the caller already has a share for this schedule, the snapshot is rebuilt and the **same** token is returned (`is_existing=true`).\n\nPass `rotate=true` to drop the caller's existing shares and mint a fresh token (use this when a previous link may have been leaked).\n\nDefaults: 30-day expiry, no rotation. The caller's account-level white-label branding is applied automatically.\n\nReturns `400 validation_error` once a schedule already has 50 active shares (counted across all teammates).","operationId":"create_scheduled_share_v1_scheduled_reports__scheduled_report_id__shares_post","parameters":[{"name":"scheduled_report_id","in":"path","required":true,"schema":{"type":"string","description":"Scheduled report UUID.","title":"Scheduled Report Id"},"description":"Scheduled report UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ScheduledReportShareCreate"},{"type":"null"}],"description":"Share config (optional; defaults to 30-day expiry, no rotation).","title":"Payload"}}}},"responses":{"201":{"description":"Created a scheduled-report share","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduledReportShare"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:scheduled","x-rankprompt-cost":{"request_units":5,"credits":0}},"delete":{"tags":["Shares"],"summary":"Revoke scheduled-report shares","description":"Revoke every share link the caller owns for this scheduled report. Idempotent: calling it again on a schedule with no shares returns `204` no-op.\n\nCannot remove shares created by other teammates.","operationId":"delete_scheduled_shares_v1_scheduled_reports__scheduled_report_id__shares_delete","parameters":[{"name":"scheduled_report_id","in":"path","required":true,"schema":{"type":"string","description":"Scheduled report UUID.","title":"Scheduled Report Id"},"description":"Scheduled report UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"204":{"description":"Revoke scheduled-report shares","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:scheduled","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/scheduled-reports/{scheduled_report_id}/shares/{share_id}":{"patch":{"tags":["Shares"],"summary":"Extend a scheduled-report share","description":"Reset a share's `expires_at` to `now + expiration_days` (1-365). Anchored to **now**: the new expiry is predictable regardless of any remaining time on the previous window.\n\nOnly the share's owner can extend it.","operationId":"update_scheduled_share_v1_scheduled_reports__scheduled_report_id__shares__share_id__patch","parameters":[{"name":"share_id","in":"path","required":true,"schema":{"type":"string","description":"Share id (UUID).","title":"Share Id"},"description":"Share id (UUID)."},{"name":"scheduled_report_id","in":"path","required":true,"schema":{"type":"string","description":"Scheduled report UUID.","title":"Scheduled Report Id"},"description":"Scheduled report UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduledReportShareUpdate"}}}},"responses":{"200":{"description":"Extend a scheduled-report share","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduledReportShare"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:scheduled","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/shares":{"get":{"tags":["Shares"],"summary":"List brand-summary shares","description":"List the caller's non-expired public brand-summary shares for a brand (newest first).\n\nOnly shares created by the authenticated principal are returned: shares created by other teammates are not visible.","operationId":"list_brand_shares_v1_brands__brand_id__shares_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned brand-summary shares","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandShareList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:brands","x-rankprompt-cost":{"request_units":1,"credits":0}},"post":{"tags":["Shares"],"summary":"Create a brand-summary share","description":"Create a public share link to a curated snapshot of a brand (selected reports + SEO pages + optional analytics + optional content).\n\nCross-tenant safety: every `report_ids`/`seo_page_ids` entry MUST belong to this brand; mixing resources from different brands returns `400 validation_error`.\n\nIf the caller already has a brand-summary share for this brand, the snapshot is rebuilt and the **same** token is returned (`is_existing=true`). Pass `rotate=true` to drop the existing share and mint a fresh token (use this when a previous link may have been leaked).\n\nDefaults: 30-day expiry, no rotation, last 28 days of analytics/content. The caller's account-level white-label branding is applied automatically.\n\nReturns `400 validation_error` once the caller already owns 50 active brand-summary shares for this brand.","operationId":"create_brand_share_v1_brands__brand_id__shares_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/BrandShareCreate"},{"type":"null"}],"description":"Share config (optional; defaults to 30-day expiry, no rotation).","title":"Payload"}}}},"responses":{"201":{"description":"Created a brand-summary share","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandShare"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:brands","x-rankprompt-cost":{"request_units":5,"credits":0}},"delete":{"tags":["Shares"],"summary":"Revoke brand-summary shares","description":"Revoke every brand-summary share the caller owns for this brand. Idempotent: calling it again on a brand with no shares returns `204` no-op.\n\nCannot remove shares created by other teammates.","operationId":"delete_brand_shares_v1_brands__brand_id__shares_delete","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"204":{"description":"Revoke brand-summary shares","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:brands","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/shares/{share_id}":{"patch":{"tags":["Shares"],"summary":"Extend a brand-summary share","description":"Reset a share's `expires_at` to `now + expiration_days` (1-365). Anchored to **now**: the new expiry is predictable regardless of any remaining time on the previous window.\n\nOnly the share's owner can extend it.","operationId":"update_brand_share_v1_brands__brand_id__shares__share_id__patch","parameters":[{"name":"share_id","in":"path","required":true,"schema":{"type":"string","description":"Share id (UUID).","title":"Share Id"},"description":"Share id (UUID)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandShareUpdate"}}}},"responses":{"200":{"description":"Extend a brand-summary share","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandShare"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:brands","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/citations":{"get":{"tags":["Citations"],"summary":"List citations","description":"Cursor-paginated list of citations discovered for the brand across recent reports.\n\nSort options (descending):\n- `created_at` (default): newest first.\n- `rankprompt_score`: highest-impact opportunities first.\n\nFilters (`page_category`, `min_rankprompt_score`, `has_backlink`, `brand_mentioned`, `unlinked`, `backlink_status`, `is_actionable`, `has_contact`, `report_id`) compose with AND. To narrow by `site_type` or `relation`, use `/citations/pages`.\n\nCursors are bound to the sort they were issued for; restart pagination with `cursor=null` when changing `sort`.","operationId":"list_citations_v1_brands__brand_id__citations_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"sort","in":"query","required":false,"schema":{"enum":["created_at","rankprompt_score"],"type":"string","description":"Sort key (descending). Default `created_at`.","default":"created_at","title":"Sort"},"description":"Sort key (descending). Default `created_at`."},{"name":"page_category","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":64},{"type":"null"}],"description":"Restrict to a single `page_category` bucket.","title":"Page Category"},"description":"Restrict to a single `page_category` bucket."},{"name":"min_rankprompt_score","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":100,"minimum":0},{"type":"null"}],"description":"Minimum `rankprompt_score` (0-100).","title":"Min Rankprompt Score"},"description":"Minimum `rankprompt_score` (0-100)."},{"name":"has_backlink","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter on whether the page backlinks to a brand domain. `false` returns only pages an Analyze or a backlink check has read; pages nobody read have `has_backlink: null` and match neither value.","title":"Has Backlink"},"description":"Filter on whether the page backlinks to a brand domain. `false` returns only pages an Analyze or a backlink check has read; pages nobody read have `has_backlink: null` and match neither value."},{"name":"brand_mentioned","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter on whether the page names the brand; only pages an Analyze read match either value.","title":"Brand Mentioned"},"description":"Filter on whether the page names the brand; only pages an Analyze read match either value."},{"name":"unlinked","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"`true`: pages that name the brand without linking to it, the easiest backlink to ask for. Only pages an Analyze read.","title":"Unlinked"},"description":"`true`: pages that name the brand without linking to it, the easiest backlink to ask for. Only pages an Analyze read."},{"name":"backlink_status","in":"query","required":false,"schema":{"anyOf":[{"enum":["live","lost","rel_changed","url_changed","unreachable"],"type":"string"},{"type":"null"}],"description":"What the newest weekly re-read of a won backlink found; `lost` lists the links that disappeared (those no longer count as `has_backlink`). Pages never re-read match no value.","title":"Backlink Status"},"description":"What the newest weekly re-read of a won backlink found; `lost` lists the links that disappeared (those no longer count as `has_backlink`). Pages never re-read match no value."},{"name":"is_actionable","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter on the convenience `is_actionable` flag.","title":"Is Actionable"},"description":"Filter on the convenience `is_actionable` flag."},{"name":"has_contact","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Only return citations with a linked contact in the CRM.","title":"Has Contact"},"description":"Only return citations with a linked contact in the CRM."},{"name":"report_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":64},{"type":"null"}],"description":"Restrict to citations that appeared in a specific report.","title":"Report Id"},"description":"Restrict to citations that appeared in a specific report."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Page size (default 20, max 100).","default":20,"title":"Limit"},"description":"Page size (default 20, max 100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Continuation token from a previous response's `next_cursor`.","title":"Cursor"},"description":"Continuation token from a previous response's `next_cursor`."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned citations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CitationList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:citations","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/citations/social":{"get":{"tags":["Citations"],"summary":"List cited social posts","description":"The Reddit posts, YouTube videos or LinkedIn posts and pages the AI answers cited for the brand, most cited first. `network` picks one; `subreddit` narrows Reddit to one community and `kind` LinkedIn to one kind of page (`post`, `article`, `person`, `company`, `school`, `showcase`, `other`).\n\nFilters compose with AND: `report_id` (repeat for several), `scheduled_report_id`, `platform` (repeat for several engines), `date_from` and `date_to`. Offset paginated via `limit` (1-500) and `offset`.","operationId":"list_social_citations_v1_brands__brand_id__citations_social_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"network","in":"query","required":true,"schema":{"enum":["reddit","youtube","linkedin"],"type":"string","description":"`reddit`, `youtube` or `linkedin`.","title":"Network"},"description":"`reddit`, `youtube` or `linkedin`."},{"name":"subreddit","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"description":"Reddit only: one subreddit, without the `r/`.","title":"Subreddit"},"description":"Reddit only: one subreddit, without the `r/`."},{"name":"kind","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"enum":["post","article","person","company","school","showcase","other"],"type":"string"}},{"type":"null"}],"description":"LinkedIn only: these kinds of page; repeat for several.","title":"Kind"},"description":"LinkedIn only: these kinds of page; repeat for several."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Posts per page (1-500, default 100).","default":100,"title":"Limit"},"description":"Posts per page (1-500, default 100)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Posts to skip from the start.","default":0,"title":"Offset"},"description":"Posts to skip from the start."},{"name":"report_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Only these reports (UUIDs); repeat the parameter for several.","title":"Report Id"},"description":"Only these reports (UUIDs); repeat the parameter for several."},{"name":"report_scope","in":"query","required":false,"schema":{"anyOf":[{"const":"all","type":"string"},{"type":"null"}],"description":"`all` for every completed report of the brand, in place of naming each one; the other filters still apply.","title":"Report Scope"},"description":"`all` for every completed report of the brand, in place of naming each one; the other filters still apply."},{"name":"scheduled_report_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only the runs of this Scheduled Report (UUID).","title":"Scheduled Report Id"},"description":"Only the runs of this Scheduled Report (UUID)."},{"name":"tracker_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":200},{"type":"null"}],"description":"Only the runs of these trackers (a report's `tracker_id`; a scheduled report's id is its tracker's); repeat the parameter for several.","title":"Tracker Id"},"description":"Only the runs of these trackers (a report's `tracker_id`; a scheduled report's id is its tracker's); repeat the parameter for several."},{"name":"market_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":200},{"type":"null"}],"description":"Only the runs in these markets (a report's `market_id`, a region config's `id`); repeat the parameter for several.","title":"Market Id"},"description":"Only the runs in these markets (a report's `market_id`, a region config's `id`); repeat the parameter for several."},{"name":"place","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","minLength":1,"maxLength":300},"maxItems":200},{"type":"null"}],"description":"Only the runs in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake, `australia|emerald|victoria`), across every tracker; repeat the parameter for several.","title":"Place"},"description":"Only the runs in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake, `australia|emerald|victoria`), across every tracker; repeat the parameter for several."},{"name":"scope","in":"query","required":false,"schema":{"anyOf":[{"enum":["default","all"],"type":"string"},{"type":"null"}],"description":"`default` reads what the app opens on (every scheduled report's runs plus the newest one-off reports) and takes no other report, tracker, market or place filter; `all` reads every completed report of the brand.","title":"Scope"},"description":"`default` reads what the app opens on (every scheduled report's runs plus the newest one-off reports) and takes no other report, tracker, market or place filter; `all` reads every completed report of the brand."},{"name":"platform","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"enum":["chatgpt","chatgpt_search","perplexity","ai_overviews","claude","claude_search","gemini","grok","muse"],"type":"string"}},{"type":"null"}],"description":"Only answers from these engines; repeat the parameter for several.","title":"Platform"},"description":"Only answers from these engines; repeat the parameter for several."},{"name":"date_from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only answers from this moment on (ISO-8601).","title":"Date From"},"description":"Only answers from this moment on (ISO-8601)."},{"name":"date_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only answers before this moment, exclusive (ISO-8601); not before `date_from`.","title":"Date To"},"description":"Only answers before this moment, exclusive (ISO-8601); not before `date_from`."},{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","maxLength":200},"maxItems":50},{"type":"null"}],"description":"Only answers to prompts of these categories; repeat the parameter for several.","title":"Category"},"description":"Only answers to prompts of these categories; repeat the parameter for several."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned cited social posts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SocialCitationList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:citations","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/citations/pages":{"get":{"tags":["Citations"],"summary":"List cited pages","description":"Every page the AI answers cited for the brand, one row per URL, counted from the answers themselves: how often, by which engines and prompts, its share of all citations and its change.\n\nFilters compose with AND: `report_id` (repeat for several), `scheduled_report_id`, `platform` (repeat for several engines), `date_from`, `date_to` and `category` (the prompt category; repeat for several). Also `site_type` and `relation` (repeat each for several; `site_type=classifying` matches pages whose site is not classified yet), `domain` and `search` (a substring of the URL or title).\n\n`sort`: `citations` (default, most cited first), `recent` (last cited first), `prompts`, `position` (best average place first), `change` (biggest gain first) or `trend` (new first, then the steepest rise). `first_half_citation_count` and `second_half_citation_count` split the runs read into their first and last half (with an odd count the middle run counts in neither), and the `change` and `trend` sorts compare the second half with the first. Offset paginated via `limit` (1-500) and `offset`.","operationId":"list_cited_pages_v1_brands__brand_id__citations_pages_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"site_type","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":20},{"type":"null"}],"description":"Only pages on these site types (an open set); repeat for several.","title":"Site Type"},"description":"Only pages on these site types (an open set); repeat for several."},{"name":"relation","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"enum":["owned","competitor","none"],"type":"string"}},{"type":"null"}],"description":"Only pages with these relations to the brand: `owned`, `competitor`, `none`.","title":"Relation"},"description":"Only pages with these relations to the brand: `owned`, `competitor`, `none`."},{"name":"domain","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":253},{"type":"null"}],"description":"Only pages on this domain.","title":"Domain"},"description":"Only pages on this domain."},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Only pages whose URL or title contains this text.","title":"Search"},"description":"Only pages whose URL or title contains this text."},{"name":"sort","in":"query","required":false,"schema":{"enum":["citations","recent","prompts","position","change","trend"],"type":"string","description":"Order of the rows. Default `citations`.","default":"citations","title":"Sort"},"description":"Order of the rows. Default `citations`."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Pages per page (1-500, default 100).","default":100,"title":"Limit"},"description":"Pages per page (1-500, default 100)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Pages to skip from the start.","default":0,"title":"Offset"},"description":"Pages to skip from the start."},{"name":"report_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Only these reports (UUIDs); repeat the parameter for several.","title":"Report Id"},"description":"Only these reports (UUIDs); repeat the parameter for several."},{"name":"report_scope","in":"query","required":false,"schema":{"anyOf":[{"const":"all","type":"string"},{"type":"null"}],"description":"`all` for every completed report of the brand, in place of naming each one; the other filters still apply.","title":"Report Scope"},"description":"`all` for every completed report of the brand, in place of naming each one; the other filters still apply."},{"name":"scheduled_report_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only the runs of this Scheduled Report (UUID).","title":"Scheduled Report Id"},"description":"Only the runs of this Scheduled Report (UUID)."},{"name":"tracker_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":200},{"type":"null"}],"description":"Only the runs of these trackers (a report's `tracker_id`; a scheduled report's id is its tracker's); repeat the parameter for several.","title":"Tracker Id"},"description":"Only the runs of these trackers (a report's `tracker_id`; a scheduled report's id is its tracker's); repeat the parameter for several."},{"name":"market_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":200},{"type":"null"}],"description":"Only the runs in these markets (a report's `market_id`, a region config's `id`); repeat the parameter for several.","title":"Market Id"},"description":"Only the runs in these markets (a report's `market_id`, a region config's `id`); repeat the parameter for several."},{"name":"place","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","minLength":1,"maxLength":300},"maxItems":200},{"type":"null"}],"description":"Only the runs in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake, `australia|emerald|victoria`), across every tracker; repeat the parameter for several.","title":"Place"},"description":"Only the runs in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake, `australia|emerald|victoria`), across every tracker; repeat the parameter for several."},{"name":"scope","in":"query","required":false,"schema":{"anyOf":[{"enum":["default","all"],"type":"string"},{"type":"null"}],"description":"`default` reads what the app opens on (every scheduled report's runs plus the newest one-off reports) and takes no other report, tracker, market or place filter; `all` reads every completed report of the brand.","title":"Scope"},"description":"`default` reads what the app opens on (every scheduled report's runs plus the newest one-off reports) and takes no other report, tracker, market or place filter; `all` reads every completed report of the brand."},{"name":"platform","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"enum":["chatgpt","chatgpt_search","perplexity","ai_overviews","claude","claude_search","gemini","grok","muse"],"type":"string"}},{"type":"null"}],"description":"Only answers from these engines; repeat the parameter for several.","title":"Platform"},"description":"Only answers from these engines; repeat the parameter for several."},{"name":"date_from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only answers from this moment on (ISO-8601).","title":"Date From"},"description":"Only answers from this moment on (ISO-8601)."},{"name":"date_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only answers before this moment, exclusive (ISO-8601); not before `date_from`.","title":"Date To"},"description":"Only answers before this moment, exclusive (ISO-8601); not before `date_from`."},{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","maxLength":200},"maxItems":50},{"type":"null"}],"description":"Only answers to prompts of these categories; repeat the parameter for several.","title":"Category"},"description":"Only answers to prompts of these categories; repeat the parameter for several."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned cited pages","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CitedPageList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:citations","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/citations/domains":{"get":{"tags":["Citations"],"summary":"List cited domains","description":"The cited pages rolled up by domain, counted from the answers under the Visibility filters, with each domain's reach across Rank Prompt. `total_citations` and `owned_citations` sum the whole window.\n\nFilters compose with AND: `report_id` (repeat for several), `scheduled_report_id`, `platform` (repeat for several engines), `date_from`, `date_to` and `category` (the prompt category; repeat for several). Also `site_type` and `relation` (repeat each for several) and `search` (a substring of the domain). A domain's `site_type` and `relation` are those of most of its cited pages.\n\n`sort`: `citations` (default), `urls`, `share`, `change`, `trend`, `avg_position` or `last_seen`. `first_half_citation_count` and `second_half_citation_count` split the runs read into their first and last half (with an odd count the middle run counts in neither), and the `change` and `trend` sorts compare the second half with the first. Offset paginated via `limit` (1-500) and `offset`.","operationId":"list_cited_domains_v1_brands__brand_id__citations_domains_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"site_type","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":20},{"type":"null"}],"description":"Only pages on these site types (an open set); repeat for several.","title":"Site Type"},"description":"Only pages on these site types (an open set); repeat for several."},{"name":"relation","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"enum":["owned","competitor","none"],"type":"string"}},{"type":"null"}],"description":"Only pages with these relations to the brand: `owned`, `competitor`, `none`.","title":"Relation"},"description":"Only pages with these relations to the brand: `owned`, `competitor`, `none`."},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Only domains containing this text.","title":"Search"},"description":"Only domains containing this text."},{"name":"sort","in":"query","required":false,"schema":{"enum":["citations","urls","share","change","trend","avg_position","last_seen"],"type":"string","description":"Order of the rows. Default `citations`.","default":"citations","title":"Sort"},"description":"Order of the rows. Default `citations`."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Domains per page (1-500, default 100).","default":100,"title":"Limit"},"description":"Domains per page (1-500, default 100)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Domains to skip from the start.","default":0,"title":"Offset"},"description":"Domains to skip from the start."},{"name":"report_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Only these reports (UUIDs); repeat the parameter for several.","title":"Report Id"},"description":"Only these reports (UUIDs); repeat the parameter for several."},{"name":"report_scope","in":"query","required":false,"schema":{"anyOf":[{"const":"all","type":"string"},{"type":"null"}],"description":"`all` for every completed report of the brand, in place of naming each one; the other filters still apply.","title":"Report Scope"},"description":"`all` for every completed report of the brand, in place of naming each one; the other filters still apply."},{"name":"scheduled_report_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only the runs of this Scheduled Report (UUID).","title":"Scheduled Report Id"},"description":"Only the runs of this Scheduled Report (UUID)."},{"name":"tracker_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":200},{"type":"null"}],"description":"Only the runs of these trackers (a report's `tracker_id`; a scheduled report's id is its tracker's); repeat the parameter for several.","title":"Tracker Id"},"description":"Only the runs of these trackers (a report's `tracker_id`; a scheduled report's id is its tracker's); repeat the parameter for several."},{"name":"market_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":200},{"type":"null"}],"description":"Only the runs in these markets (a report's `market_id`, a region config's `id`); repeat the parameter for several.","title":"Market Id"},"description":"Only the runs in these markets (a report's `market_id`, a region config's `id`); repeat the parameter for several."},{"name":"place","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","minLength":1,"maxLength":300},"maxItems":200},{"type":"null"}],"description":"Only the runs in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake, `australia|emerald|victoria`), across every tracker; repeat the parameter for several.","title":"Place"},"description":"Only the runs in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake, `australia|emerald|victoria`), across every tracker; repeat the parameter for several."},{"name":"scope","in":"query","required":false,"schema":{"anyOf":[{"enum":["default","all"],"type":"string"},{"type":"null"}],"description":"`default` reads what the app opens on (every scheduled report's runs plus the newest one-off reports) and takes no other report, tracker, market or place filter; `all` reads every completed report of the brand.","title":"Scope"},"description":"`default` reads what the app opens on (every scheduled report's runs plus the newest one-off reports) and takes no other report, tracker, market or place filter; `all` reads every completed report of the brand."},{"name":"platform","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"enum":["chatgpt","chatgpt_search","perplexity","ai_overviews","claude","claude_search","gemini","grok","muse"],"type":"string"}},{"type":"null"}],"description":"Only answers from these engines; repeat the parameter for several.","title":"Platform"},"description":"Only answers from these engines; repeat the parameter for several."},{"name":"date_from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only answers from this moment on (ISO-8601).","title":"Date From"},"description":"Only answers from this moment on (ISO-8601)."},{"name":"date_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only answers before this moment, exclusive (ISO-8601); not before `date_from`.","title":"Date To"},"description":"Only answers before this moment, exclusive (ISO-8601); not before `date_from`."},{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","maxLength":200},"maxItems":50},{"type":"null"}],"description":"Only answers to prompts of these categories; repeat the parameter for several.","title":"Category"},"description":"Only answers to prompts of these categories; repeat the parameter for several."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned cited domains","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CitedDomainList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:citations","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/citations/series":{"get":{"tags":["Citations"],"summary":"Citations over time","description":"Citations per day or week, one point per bucket and key, with every answer in the bucket so a share can be drawn. `group` picks the key: `site_type` (default; `classifying` while a site is not classified yet), `relation`, `page_category`, `domain` or `url`; `domain` and `url` need the keys to chart in `key` (repeat, up to 50). An answer with no engine recorded counts in neither its citations nor its answers, as in the answers per day and engine.\n\nFilters compose with AND: `report_id` (repeat for several), `scheduled_report_id`, `platform` (repeat for several engines), `date_from`, `date_to` and `category` (the prompt category; repeat for several). `bucket` is `day` (default) or `week`, counted in `tz` (an IANA zone, default `UTC`; a week starts on Monday). Returns every point, oldest first.","operationId":"citation_series_v1_brands__brand_id__citations_series_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"group","in":"query","required":false,"schema":{"enum":["site_type","relation","domain","page_category","url"],"type":"string","description":"What each line counts.","default":"site_type","title":"Group"},"description":"What each line counts."},{"name":"key","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":50},{"type":"null"}],"description":"Only these site types, relations, categories, domains or URLs; repeat for several.","title":"Key"},"description":"Only these site types, relations, categories, domains or URLs; repeat for several."},{"name":"bucket","in":"query","required":false,"schema":{"enum":["day","week"],"type":"string","description":"`day` (default) or `week`.","default":"day","title":"Bucket"},"description":"`day` (default) or `week`."},{"name":"tz","in":"query","required":false,"schema":{"type":"string","maxLength":64,"description":"IANA time zone the days and weeks are counted in, e.g. `America/New_York`. Default `UTC`.","default":"UTC","title":"Tz"},"description":"IANA time zone the days and weeks are counted in, e.g. `America/New_York`. Default `UTC`."},{"name":"report_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Only these reports (UUIDs); repeat the parameter for several.","title":"Report Id"},"description":"Only these reports (UUIDs); repeat the parameter for several."},{"name":"report_scope","in":"query","required":false,"schema":{"anyOf":[{"const":"all","type":"string"},{"type":"null"}],"description":"`all` for every completed report of the brand, in place of naming each one; the other filters still apply.","title":"Report Scope"},"description":"`all` for every completed report of the brand, in place of naming each one; the other filters still apply."},{"name":"scheduled_report_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only the runs of this Scheduled Report (UUID).","title":"Scheduled Report Id"},"description":"Only the runs of this Scheduled Report (UUID)."},{"name":"tracker_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":200},{"type":"null"}],"description":"Only the runs of these trackers (a report's `tracker_id`; a scheduled report's id is its tracker's); repeat the parameter for several.","title":"Tracker Id"},"description":"Only the runs of these trackers (a report's `tracker_id`; a scheduled report's id is its tracker's); repeat the parameter for several."},{"name":"market_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":200},{"type":"null"}],"description":"Only the runs in these markets (a report's `market_id`, a region config's `id`); repeat the parameter for several.","title":"Market Id"},"description":"Only the runs in these markets (a report's `market_id`, a region config's `id`); repeat the parameter for several."},{"name":"place","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","minLength":1,"maxLength":300},"maxItems":200},{"type":"null"}],"description":"Only the runs in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake, `australia|emerald|victoria`), across every tracker; repeat the parameter for several.","title":"Place"},"description":"Only the runs in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake, `australia|emerald|victoria`), across every tracker; repeat the parameter for several."},{"name":"scope","in":"query","required":false,"schema":{"anyOf":[{"enum":["default","all"],"type":"string"},{"type":"null"}],"description":"`default` reads what the app opens on (every scheduled report's runs plus the newest one-off reports) and takes no other report, tracker, market or place filter; `all` reads every completed report of the brand.","title":"Scope"},"description":"`default` reads what the app opens on (every scheduled report's runs plus the newest one-off reports) and takes no other report, tracker, market or place filter; `all` reads every completed report of the brand."},{"name":"platform","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"enum":["chatgpt","chatgpt_search","perplexity","ai_overviews","claude","claude_search","gemini","grok","muse"],"type":"string"}},{"type":"null"}],"description":"Only answers from these engines; repeat the parameter for several.","title":"Platform"},"description":"Only answers from these engines; repeat the parameter for several."},{"name":"date_from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only answers from this moment on (ISO-8601).","title":"Date From"},"description":"Only answers from this moment on (ISO-8601)."},{"name":"date_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only answers before this moment, exclusive (ISO-8601); not before `date_from`.","title":"Date To"},"description":"Only answers before this moment, exclusive (ISO-8601); not before `date_from`."},{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","maxLength":200},"maxItems":50},{"type":"null"}],"description":"Only answers to prompts of these categories; repeat the parameter for several.","title":"Category"},"description":"Only answers to prompts of these categories; repeat the parameter for several."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Citations over time","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CitationSeries"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:citations","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/citations/social/groups":{"get":{"tags":["Citations"],"summary":"List cited subreddits, channels and authors","description":"The social posts the answers cited, rolled up by where they live: subreddits for `reddit`, channels for `youtube`, authors for `linkedin`, most cited first. A subreddit's `key` narrows `GET /v1/brands/{brand_id}/citations/social` through `subreddit`.\n\nFilters compose with AND: `report_id` (repeat for several), `scheduled_report_id`, `platform` (repeat for several engines), `date_from`, `date_to` and `category` (the prompt category; repeat for several). Also `search` (a substring of the name) and `key` (only the group with that `key`). Offset paginated via `limit` (1-500) and `offset`; `total_items` and `total_citations` sum every group.","operationId":"list_social_groups_v1_brands__brand_id__citations_social_groups_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"network","in":"query","required":true,"schema":{"enum":["reddit","youtube","linkedin"],"type":"string","description":"`reddit`, `youtube` or `linkedin`.","title":"Network"},"description":"`reddit`, `youtube` or `linkedin`."},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Only groups whose name contains this.","title":"Search"},"description":"Only groups whose name contains this."},{"name":"key","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Only the group with this `key`.","title":"Key"},"description":"Only the group with this `key`."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Groups per page (1-500, default 100).","default":100,"title":"Limit"},"description":"Groups per page (1-500, default 100)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Groups to skip from the start.","default":0,"title":"Offset"},"description":"Groups to skip from the start."},{"name":"report_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Only these reports (UUIDs); repeat the parameter for several.","title":"Report Id"},"description":"Only these reports (UUIDs); repeat the parameter for several."},{"name":"report_scope","in":"query","required":false,"schema":{"anyOf":[{"const":"all","type":"string"},{"type":"null"}],"description":"`all` for every completed report of the brand, in place of naming each one; the other filters still apply.","title":"Report Scope"},"description":"`all` for every completed report of the brand, in place of naming each one; the other filters still apply."},{"name":"scheduled_report_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only the runs of this Scheduled Report (UUID).","title":"Scheduled Report Id"},"description":"Only the runs of this Scheduled Report (UUID)."},{"name":"tracker_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":200},{"type":"null"}],"description":"Only the runs of these trackers (a report's `tracker_id`; a scheduled report's id is its tracker's); repeat the parameter for several.","title":"Tracker Id"},"description":"Only the runs of these trackers (a report's `tracker_id`; a scheduled report's id is its tracker's); repeat the parameter for several."},{"name":"market_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":200},{"type":"null"}],"description":"Only the runs in these markets (a report's `market_id`, a region config's `id`); repeat the parameter for several.","title":"Market Id"},"description":"Only the runs in these markets (a report's `market_id`, a region config's `id`); repeat the parameter for several."},{"name":"place","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","minLength":1,"maxLength":300},"maxItems":200},{"type":"null"}],"description":"Only the runs in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake, `australia|emerald|victoria`), across every tracker; repeat the parameter for several.","title":"Place"},"description":"Only the runs in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake, `australia|emerald|victoria`), across every tracker; repeat the parameter for several."},{"name":"scope","in":"query","required":false,"schema":{"anyOf":[{"enum":["default","all"],"type":"string"},{"type":"null"}],"description":"`default` reads what the app opens on (every scheduled report's runs plus the newest one-off reports) and takes no other report, tracker, market or place filter; `all` reads every completed report of the brand.","title":"Scope"},"description":"`default` reads what the app opens on (every scheduled report's runs plus the newest one-off reports) and takes no other report, tracker, market or place filter; `all` reads every completed report of the brand."},{"name":"platform","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"enum":["chatgpt","chatgpt_search","perplexity","ai_overviews","claude","claude_search","gemini","grok","muse"],"type":"string"}},{"type":"null"}],"description":"Only answers from these engines; repeat the parameter for several.","title":"Platform"},"description":"Only answers from these engines; repeat the parameter for several."},{"name":"date_from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only answers from this moment on (ISO-8601).","title":"Date From"},"description":"Only answers from this moment on (ISO-8601)."},{"name":"date_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only answers before this moment, exclusive (ISO-8601); not before `date_from`.","title":"Date To"},"description":"Only answers before this moment, exclusive (ISO-8601); not before `date_from`."},{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","maxLength":200},"maxItems":50},{"type":"null"}],"description":"Only answers to prompts of these categories; repeat the parameter for several.","title":"Category"},"description":"Only answers to prompts of these categories; repeat the parameter for several."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned cited subreddits, channels and authors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SocialGroupList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:citations","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/citations/{citation_id}":{"get":{"tags":["Citations"],"summary":"Retrieve a citation","description":"Fetch a single citation by id, including domain metadata, Rank Prompt score, and the report context where it was discovered.\n\nCross-brand requests return `404 not_found` (instead of `403`) to avoid leaking citation existence across tenants.","operationId":"get_citation_v1_citations__citation_id__get","parameters":[{"name":"citation_id","in":"path","required":true,"schema":{"type":"string","description":"Citation id (UUID).","title":"Citation Id"},"description":"Citation id (UUID)."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned a citation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Citation"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:citations","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/citations/{citation_id}/backlink-checks":{"get":{"tags":["Citations"],"summary":"List a citation's backlink re-checks","description":"The weekly re-reads of a won backlink, newest first: whether the link was still there, gone, restricted or pointing elsewhere. The platform re-reads every won backlink about once a week at no cost; `POST /citations/{citation_id}/backlink-verifications` checks now for a credit. Starter plan.","operationId":"list_backlink_checks_v1_citations__citation_id__backlink_checks_get","parameters":[{"name":"citation_id","in":"path","required":true,"schema":{"type":"string","description":"Citation id (UUID).","title":"Citation Id"},"description":"Citation id (UUID)."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Page size (1-100).","default":20,"title":"Limit"},"description":"Page size (1-100)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Checks to skip.","default":0,"title":"Offset"},"description":"Checks to skip."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned a citation's backlink re-checks","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BacklinkCheckList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:citations","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/prompts":{"get":{"tags":["Prompts"],"summary":"List brand prompts","description":"Every prompt the brand tracks in a Scheduled Report or ran in a one-off report, one row per prompt text, with its runs, visibility, best position, visibility on the last 12 days it was answered and the Google keyword behind it. Every answer of the selected runs counts: `platform_results` gives the answers, mentions and the brand's mean position per engine, `brands_named` the brands those answers name (the brand where `brand_appears` is true, a registered competitor under its canonical name) and `domains_cited` the domains they cite, each with its answers and mean first place, most answers first, then the better position, then the name.\n\nFilters compose with AND: `scheduled_report_id`, `tracking` (`active`: in a running schedule, `paused`: scheduled but not running, `one_off`: never scheduled, or not in the one `scheduled_report_id` names), `type` (`brand`, `competitor`, `organic`) and `intent` (of the mapped keyword, `unmapped` for none), each repeatable for several, `category` (the prompt's current category: its tracked one, else the one it ran under; repeat for several), `search` (a substring of the text) and `prompt_hash` (one prompt text). `brands_named` and `domains_cited` come only with `detail=true`, the costly part, at most 100 rows a page. The Visibility filters `report_id` (repeat for several), `platform` (repeat for several engines), `date_from` and `date_to` narrow the answers each row counts to those reports, engines and period, by the date of each answer.\n\n`facets` counts the prompts by `type`, `intent` and category across every page, each count under every filter but its own, so it says what picking that value would return.\n\n`sort`: `runs` (default, most run first), `visibility` (highest first), `recent` (last run first) or `text` (alphabetical). `tz` (an IANA zone, default `UTC`) is the zone the trend's days are counted in. Offset paginated via `limit` (1-500) and `offset`.","operationId":"list_brand_prompts_v1_brands__brand_id__prompts_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"tracking","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"enum":["active","paused","one_off"],"type":"string"}},{"type":"null"}],"description":"`active`, `paused` or `one_off`; repeat the parameter for several.","title":"Tracking"},"description":"`active`, `paused` or `one_off`; repeat the parameter for several."},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"enum":["brand","competitor","organic"],"type":"string"}},{"type":"null"}],"description":"`brand`, `competitor` or `organic`; repeat the parameter for several.","title":"Type"},"description":"`brand`, `competitor` or `organic`; repeat the parameter for several."},{"name":"intent","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"enum":["informational","commercial","transactional","navigational","local","unmapped"],"type":"string"}},{"type":"null"}],"description":"Search intent of the mapped keyword, `unmapped` for prompts without one; repeat the parameter for several.","title":"Intent"},"description":"Search intent of the mapped keyword, `unmapped` for prompts without one; repeat the parameter for several."},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Only prompts containing this text (case-insensitive).","title":"Search"},"description":"Only prompts containing this text (case-insensitive)."},{"name":"prompt_hash","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^[0-9a-f]{40}$"},{"type":"null"}],"description":"Only this prompt text (its `prompt_hash`).","title":"Prompt Hash"},"description":"Only this prompt text (its `prompt_hash`)."},{"name":"detail","in":"query","required":false,"schema":{"type":"boolean","description":"`true` adds `brands_named` and `domains_cited`, a slower read capped at 100 rows a page. Default `false`.","default":false,"title":"Detail"},"description":"`true` adds `brands_named` and `domains_cited`, a slower read capped at 100 rows a page. Default `false`."},{"name":"sort","in":"query","required":false,"schema":{"enum":["runs","visibility","recent","text"],"type":"string","description":"Order of the rows. Default `runs`.","default":"runs","title":"Sort"},"description":"Order of the rows. Default `runs`."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Prompts per page (1-500, default 100).","default":100,"title":"Limit"},"description":"Prompts per page (1-500, default 100)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Prompts to skip from the start.","default":0,"title":"Offset"},"description":"Prompts to skip from the start."},{"name":"tz","in":"query","required":false,"schema":{"type":"string","maxLength":64,"description":"IANA time zone the days are counted in, e.g. `America/New_York`. Default `UTC`.","default":"UTC","title":"Tz"},"description":"IANA time zone the days are counted in, e.g. `America/New_York`. Default `UTC`."},{"name":"report_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Only these reports (UUIDs); repeat the parameter for several.","title":"Report Id"},"description":"Only these reports (UUIDs); repeat the parameter for several."},{"name":"report_scope","in":"query","required":false,"schema":{"anyOf":[{"const":"all","type":"string"},{"type":"null"}],"description":"`all` for every completed report of the brand, in place of naming each one; the other filters still apply.","title":"Report Scope"},"description":"`all` for every completed report of the brand, in place of naming each one; the other filters still apply."},{"name":"scheduled_report_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only the runs of this Scheduled Report (UUID).","title":"Scheduled Report Id"},"description":"Only the runs of this Scheduled Report (UUID)."},{"name":"tracker_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":200},{"type":"null"}],"description":"Only the runs of these trackers (a report's `tracker_id`; a scheduled report's id is its tracker's); repeat the parameter for several.","title":"Tracker Id"},"description":"Only the runs of these trackers (a report's `tracker_id`; a scheduled report's id is its tracker's); repeat the parameter for several."},{"name":"market_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":200},{"type":"null"}],"description":"Only the runs in these markets (a report's `market_id`, a region config's `id`); repeat the parameter for several.","title":"Market Id"},"description":"Only the runs in these markets (a report's `market_id`, a region config's `id`); repeat the parameter for several."},{"name":"place","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","minLength":1,"maxLength":300},"maxItems":200},{"type":"null"}],"description":"Only the runs in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake, `australia|emerald|victoria`), across every tracker; repeat the parameter for several.","title":"Place"},"description":"Only the runs in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake, `australia|emerald|victoria`), across every tracker; repeat the parameter for several."},{"name":"scope","in":"query","required":false,"schema":{"anyOf":[{"enum":["default","all"],"type":"string"},{"type":"null"}],"description":"`default` reads what the app opens on (every scheduled report's runs plus the newest one-off reports) and takes no other report, tracker, market or place filter; `all` reads every completed report of the brand.","title":"Scope"},"description":"`default` reads what the app opens on (every scheduled report's runs plus the newest one-off reports) and takes no other report, tracker, market or place filter; `all` reads every completed report of the brand."},{"name":"platform","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"enum":["chatgpt","chatgpt_search","perplexity","ai_overviews","claude","claude_search","gemini","grok","muse"],"type":"string"}},{"type":"null"}],"description":"Only answers from these engines; repeat the parameter for several.","title":"Platform"},"description":"Only answers from these engines; repeat the parameter for several."},{"name":"date_from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only answers from this moment on (ISO-8601).","title":"Date From"},"description":"Only answers from this moment on (ISO-8601)."},{"name":"date_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only answers before this moment, exclusive (ISO-8601); not before `date_from`.","title":"Date To"},"description":"Only answers before this moment, exclusive (ISO-8601); not before `date_from`."},{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","maxLength":200},"maxItems":50},{"type":"null"}],"description":"Only answers to prompts of these categories; repeat the parameter for several.","title":"Category"},"description":"Only answers to prompts of these categories; repeat the parameter for several."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned brand prompts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandPromptList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:reports","x-rankprompt-cost":{"request_units":2,"credits":0}},"patch":{"tags":["Prompts"],"summary":"Update brand prompts in bulk","description":"Pause, resume, re-categorize or set the funnel `intent` of many tracked prompts in one call, across every Scheduled Report and location of the brand. `ids` are the `tracked[].id` of the rows from `GET /v1/brands/{brand_id}/prompts` (the same ids as `/v1/region-configs/{id}/prompts`); a prompt every region config of a schedule shares changes in all of them. One-off report prompts stay as they ran.\n\nEvery id is checked first: one that is not a tracked prompt of the brand answers `404 not_found` and changes nothing. The update then runs in batches, so a server error can leave part of the list changed; sending the same call again is safe. Resuming reactivates a paused location that gets prompts back. Requires EDITOR on the brand.","operationId":"update_brand_prompts_v1_brands__brand_id__prompts_patch","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandPromptsUpdate"}}}},"responses":{"200":{"description":"Updated brand prompts in bulk","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandPromptsUpdated"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:region-configs","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/prompts/answers/series":{"get":{"tags":["Prompts"],"summary":"Answers per day and engine","description":"Every answer the engines gave to the brand's prompts, counted per day in `tz` (default `UTC`) and engine, with how many named the brand. `mentioned / answers` is that engine's visibility on that day.\n\nTakes the Visibility filters, composed with AND: `report_id` (repeat for several), `scheduled_report_id`, `platform` (repeat for several engines), `date_from`, `date_to` and `category` (the prompt's current category, as the prompt rows group it; repeat for several). Returns every row, oldest day first: the series is bounded by days times engines.","operationId":"prompt_answer_series_v1_brands__brand_id__prompts_answers_series_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"tz","in":"query","required":false,"schema":{"type":"string","maxLength":64,"description":"IANA time zone the days are counted in, e.g. `America/New_York`. Default `UTC`.","default":"UTC","title":"Tz"},"description":"IANA time zone the days are counted in, e.g. `America/New_York`. Default `UTC`."},{"name":"report_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Only these reports (UUIDs); repeat the parameter for several.","title":"Report Id"},"description":"Only these reports (UUIDs); repeat the parameter for several."},{"name":"report_scope","in":"query","required":false,"schema":{"anyOf":[{"const":"all","type":"string"},{"type":"null"}],"description":"`all` for every completed report of the brand, in place of naming each one; the other filters still apply.","title":"Report Scope"},"description":"`all` for every completed report of the brand, in place of naming each one; the other filters still apply."},{"name":"scheduled_report_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only the runs of this Scheduled Report (UUID).","title":"Scheduled Report Id"},"description":"Only the runs of this Scheduled Report (UUID)."},{"name":"tracker_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":200},{"type":"null"}],"description":"Only the runs of these trackers (a report's `tracker_id`; a scheduled report's id is its tracker's); repeat the parameter for several.","title":"Tracker Id"},"description":"Only the runs of these trackers (a report's `tracker_id`; a scheduled report's id is its tracker's); repeat the parameter for several."},{"name":"market_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":200},{"type":"null"}],"description":"Only the runs in these markets (a report's `market_id`, a region config's `id`); repeat the parameter for several.","title":"Market Id"},"description":"Only the runs in these markets (a report's `market_id`, a region config's `id`); repeat the parameter for several."},{"name":"place","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","minLength":1,"maxLength":300},"maxItems":200},{"type":"null"}],"description":"Only the runs in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake, `australia|emerald|victoria`), across every tracker; repeat the parameter for several.","title":"Place"},"description":"Only the runs in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake, `australia|emerald|victoria`), across every tracker; repeat the parameter for several."},{"name":"scope","in":"query","required":false,"schema":{"anyOf":[{"enum":["default","all"],"type":"string"},{"type":"null"}],"description":"`default` reads what the app opens on (every scheduled report's runs plus the newest one-off reports) and takes no other report, tracker, market or place filter; `all` reads every completed report of the brand.","title":"Scope"},"description":"`default` reads what the app opens on (every scheduled report's runs plus the newest one-off reports) and takes no other report, tracker, market or place filter; `all` reads every completed report of the brand."},{"name":"platform","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"enum":["chatgpt","chatgpt_search","perplexity","ai_overviews","claude","claude_search","gemini","grok","muse"],"type":"string"}},{"type":"null"}],"description":"Only answers from these engines; repeat the parameter for several.","title":"Platform"},"description":"Only answers from these engines; repeat the parameter for several."},{"name":"date_from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only answers from this moment on (ISO-8601).","title":"Date From"},"description":"Only answers from this moment on (ISO-8601)."},{"name":"date_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only answers before this moment, exclusive (ISO-8601); not before `date_from`.","title":"Date To"},"description":"Only answers before this moment, exclusive (ISO-8601); not before `date_from`."},{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","maxLength":200},"maxItems":50},{"type":"null"}],"description":"Only answers to prompts of these categories; repeat the parameter for several.","title":"Category"},"description":"Only answers to prompts of these categories; repeat the parameter for several."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Answers per day and engine","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromptAnswerSeries"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:reports","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/prompts/answers/brands":{"get":{"tags":["Prompts"],"summary":"Brands the answers name","description":"The brands every answer under the filters names, each counted once per answer: the brand under its own name and its aliases in exactly the answers whose `brand_appears` is true, a registered competitor under its canonical name and relation with its aliases, a removed competitor left out. Every business the answers name counts, publishers and AI platforms included. Most answers first, then the better mean first place, then the name.\n\nTakes the Visibility filters, composed with AND: `report_id` (repeat for several), `scheduled_report_id`, `platform` (repeat for several engines), `date_from`, `date_to` and `category` (repeat for several). With none of `report_id`, `scheduled_report_id`, `date_from` or `date_to` it reads the last 90 days; pass `date_from` for a longer period. Offset paginated via `limit` (1-100, default 10) and `offset`.","operationId":"prompt_answer_brands_v1_brands__brand_id__prompts_answers_brands_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Brands per page (1-100, default 10).","default":10,"title":"Limit"},"description":"Brands per page (1-100, default 10)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Brands to skip from the start.","default":0,"title":"Offset"},"description":"Brands to skip from the start."},{"name":"report_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Only these reports (UUIDs); repeat the parameter for several.","title":"Report Id"},"description":"Only these reports (UUIDs); repeat the parameter for several."},{"name":"report_scope","in":"query","required":false,"schema":{"anyOf":[{"const":"all","type":"string"},{"type":"null"}],"description":"`all` for every completed report of the brand, in place of naming each one; the other filters still apply.","title":"Report Scope"},"description":"`all` for every completed report of the brand, in place of naming each one; the other filters still apply."},{"name":"scheduled_report_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only the runs of this Scheduled Report (UUID).","title":"Scheduled Report Id"},"description":"Only the runs of this Scheduled Report (UUID)."},{"name":"tracker_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":200},{"type":"null"}],"description":"Only the runs of these trackers (a report's `tracker_id`; a scheduled report's id is its tracker's); repeat the parameter for several.","title":"Tracker Id"},"description":"Only the runs of these trackers (a report's `tracker_id`; a scheduled report's id is its tracker's); repeat the parameter for several."},{"name":"market_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":200},{"type":"null"}],"description":"Only the runs in these markets (a report's `market_id`, a region config's `id`); repeat the parameter for several.","title":"Market Id"},"description":"Only the runs in these markets (a report's `market_id`, a region config's `id`); repeat the parameter for several."},{"name":"place","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","minLength":1,"maxLength":300},"maxItems":200},{"type":"null"}],"description":"Only the runs in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake, `australia|emerald|victoria`), across every tracker; repeat the parameter for several.","title":"Place"},"description":"Only the runs in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake, `australia|emerald|victoria`), across every tracker; repeat the parameter for several."},{"name":"scope","in":"query","required":false,"schema":{"anyOf":[{"enum":["default","all"],"type":"string"},{"type":"null"}],"description":"`default` reads what the app opens on (every scheduled report's runs plus the newest one-off reports) and takes no other report, tracker, market or place filter; `all` reads every completed report of the brand.","title":"Scope"},"description":"`default` reads what the app opens on (every scheduled report's runs plus the newest one-off reports) and takes no other report, tracker, market or place filter; `all` reads every completed report of the brand."},{"name":"platform","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"enum":["chatgpt","chatgpt_search","perplexity","ai_overviews","claude","claude_search","gemini","grok","muse"],"type":"string"}},{"type":"null"}],"description":"Only answers from these engines; repeat the parameter for several.","title":"Platform"},"description":"Only answers from these engines; repeat the parameter for several."},{"name":"date_from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only answers from this moment on (ISO-8601).","title":"Date From"},"description":"Only answers from this moment on (ISO-8601)."},{"name":"date_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only answers before this moment, exclusive (ISO-8601); not before `date_from`.","title":"Date To"},"description":"Only answers before this moment, exclusive (ISO-8601); not before `date_from`."},{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","maxLength":200},"maxItems":50},{"type":"null"}],"description":"Only answers to prompts of these categories; repeat the parameter for several.","title":"Category"},"description":"Only answers to prompts of these categories; repeat the parameter for several."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Brands the answers name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromptAnswerBrandCountList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:reports","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/prompts/answers":{"get":{"tags":["Prompts"],"summary":"List prompt answers","description":"Every answer the engines gave to the brand's prompts in completed reports, newest first: the engine, model, prompt, whether and where it named the brand, the brands it names and how many URLs it cites. Read one in full, text and citations included, with `GET /v1/brands/{brand_id}/prompts/answers/{answer_id}`.\n\nFilters compose with AND: the Visibility filters `report_id` (repeat for several), `scheduled_report_id`, `platform` (repeat for several engines), `date_from`, `date_to` and `category` (repeat for several), plus `prompt_hash` (the answers to one prompt, the `prompt_hash` of `GET /v1/brands/{brand_id}/prompts`, in every market that asks it; or one market's text, a `markets[].prompt_hash`), `mentioned` (`true`: only answers naming the brand, `false`: only those that do not), `named` (only answers naming that brand or competitor, a `brands_named[].name`), `domain` (only answers citing a page of that domain, a `domains_cited[].domain`; a scheme, a path and a leading `www.` are ignored) and `search` (a substring of the prompt).\n\nCursor paginated via `limit` (1-100, default 20) and `cursor`; keep the filters when you pass `next_cursor` back.","operationId":"list_prompt_answers_v1_brands__brand_id__prompts_answers_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"prompt_hash","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^[0-9a-f]{40}$"},{"type":"null"}],"description":"Only the answers to this prompt (its `prompt_hash`, every market) or one market's text.","title":"Prompt Hash"},"description":"Only the answers to this prompt (its `prompt_hash`, every market) or one market's text."},{"name":"mentioned","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"`true`: only answers naming the brand. `false`: only those that do not.","title":"Mentioned"},"description":"`true`: only answers naming the brand. `false`: only those that do not."},{"name":"named","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Only answers naming this brand or competitor (a `brands_named[].name`).","title":"Named"},"description":"Only answers naming this brand or competitor (a `brands_named[].name`)."},{"name":"domain","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":253},{"type":"null"}],"description":"Only answers citing a page of this domain (a `domains_cited[].domain`); `www.` is ignored.","title":"Domain"},"description":"Only answers citing a page of this domain (a `domains_cited[].domain`); `www.` is ignored."},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Only answers to prompts containing this text (case-insensitive).","title":"Search"},"description":"Only answers to prompts containing this text (case-insensitive)."},{"name":"report_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Only these reports (UUIDs); repeat the parameter for several.","title":"Report Id"},"description":"Only these reports (UUIDs); repeat the parameter for several."},{"name":"report_scope","in":"query","required":false,"schema":{"anyOf":[{"const":"all","type":"string"},{"type":"null"}],"description":"`all` for every completed report of the brand, in place of naming each one; the other filters still apply.","title":"Report Scope"},"description":"`all` for every completed report of the brand, in place of naming each one; the other filters still apply."},{"name":"scheduled_report_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only the runs of this Scheduled Report (UUID).","title":"Scheduled Report Id"},"description":"Only the runs of this Scheduled Report (UUID)."},{"name":"tracker_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":200},{"type":"null"}],"description":"Only the runs of these trackers (a report's `tracker_id`; a scheduled report's id is its tracker's); repeat the parameter for several.","title":"Tracker Id"},"description":"Only the runs of these trackers (a report's `tracker_id`; a scheduled report's id is its tracker's); repeat the parameter for several."},{"name":"market_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":200},{"type":"null"}],"description":"Only the runs in these markets (a report's `market_id`, a region config's `id`); repeat the parameter for several.","title":"Market Id"},"description":"Only the runs in these markets (a report's `market_id`, a region config's `id`); repeat the parameter for several."},{"name":"place","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","minLength":1,"maxLength":300},"maxItems":200},{"type":"null"}],"description":"Only the runs in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake, `australia|emerald|victoria`), across every tracker; repeat the parameter for several.","title":"Place"},"description":"Only the runs in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake, `australia|emerald|victoria`), across every tracker; repeat the parameter for several."},{"name":"scope","in":"query","required":false,"schema":{"anyOf":[{"enum":["default","all"],"type":"string"},{"type":"null"}],"description":"`default` reads what the app opens on (every scheduled report's runs plus the newest one-off reports) and takes no other report, tracker, market or place filter; `all` reads every completed report of the brand.","title":"Scope"},"description":"`default` reads what the app opens on (every scheduled report's runs plus the newest one-off reports) and takes no other report, tracker, market or place filter; `all` reads every completed report of the brand."},{"name":"platform","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"enum":["chatgpt","chatgpt_search","perplexity","ai_overviews","claude","claude_search","gemini","grok","muse"],"type":"string"}},{"type":"null"}],"description":"Only answers from these engines; repeat the parameter for several.","title":"Platform"},"description":"Only answers from these engines; repeat the parameter for several."},{"name":"date_from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only answers from this moment on (ISO-8601).","title":"Date From"},"description":"Only answers from this moment on (ISO-8601)."},{"name":"date_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only answers before this moment, exclusive (ISO-8601); not before `date_from`.","title":"Date To"},"description":"Only answers before this moment, exclusive (ISO-8601); not before `date_from`."},{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","maxLength":200},"maxItems":50},{"type":"null"}],"description":"Only answers to prompts of these categories; repeat the parameter for several.","title":"Category"},"description":"Only answers to prompts of these categories; repeat the parameter for several."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Page size (default 20, max 100).","default":20,"title":"Limit"},"description":"Page size (default 20, max 100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Continuation token from a previous response's `next_cursor`.","title":"Cursor"},"description":"Continuation token from a previous response's `next_cursor`."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned prompt answers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromptAnswerList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:reports","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/prompts/answers/{answer_id}":{"get":{"tags":["Prompts"],"summary":"Retrieve a prompt answer","description":"One engine answer in full: the prompt, the engine and model, whether and where it named the brand, the answer text, the pages it cites (`citations`) and the ones it read without citing (`retrieved`), and the businesses it names with their category. `answer_id` is an `id` from `GET /v1/brands/{brand_id}/prompts/answers`. An answer of another brand is `404 not_found`.","operationId":"get_prompt_answer_v1_brands__brand_id__prompts_answers__answer_id__get","parameters":[{"name":"answer_id","in":"path","required":true,"schema":{"type":"string","title":"Answer Id"}},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned a prompt answer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromptAnswerDetail"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:reports","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/prompts/{prompt_hash}/content-suggestion":{"get":{"tags":["Prompts"],"summary":"Suggest content for a prompt","description":"What to do about a prompt the brand is not winning. When a page of the brand's own site is cited in its answers, `mode` is `optimize` with that page's `url`: pass it to `POST /v1/brands/{brand_id}/content-optimizations`. Otherwise `mode` is `create` with the `suggested_format` that fits it: pass it to `POST /v1/brands/{brand_id}/content-briefs/generations` with the `prompt_id` in `source_prompt_ids`.\n\n`prompt_hash` is a row's `prompt_hash` from `GET /v1/brands/{brand_id}/prompts`. Free. The format of a new article comes from a model call cached seven days per prompt; calls past the plan's daily or monthly allowance answer `429 rate_limit_exceeded` with `Retry-After` until the window resets.","operationId":"get_prompt_content_suggestion_v1_brands__brand_id__prompts__prompt_hash__content_suggestion_get","parameters":[{"name":"prompt_hash","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-f]{40}$","description":"A prompt row's `prompt_hash`.","title":"Prompt Hash"},"description":"A prompt row's `prompt_hash`."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Suggest content for a prompt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromptContentSuggestion"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:content","x-rankprompt-cost":{"request_units":2,"credits":0},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}}},"/v1/brands/{brand_id}/prompts/{prompt_hash}/cited-pages":{"get":{"tags":["Prompts"],"summary":"List the pages cited for a prompt","description":"The five pages the engines cited most answering this prompt, the most cited first, never the brand's own site: the pages a new article or an optimization should beat, to pass as `reference_urls` to `POST /v1/brands/{brand_id}/content-optimizations` or as sources of a generation.\n\n`prompt_hash` is a row's `prompt_hash` from `GET /v1/brands/{brand_id}/prompts`. Free.","operationId":"list_prompt_cited_pages_v1_brands__brand_id__prompts__prompt_hash__cited_pages_get","parameters":[{"name":"prompt_hash","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-f]{40}$","description":"A prompt row's `prompt_hash`.","title":"Prompt Hash"},"description":"A prompt row's `prompt_hash`."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned the pages cited for a prompt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromptCitedPageList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:citations","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/fanouts":{"get":{"tags":["Fanouts"],"summary":"List fan-out searches","description":"Each distinct web search the engines ran while answering the brand's prompts, most frequent first. These are the queries behind the citations: what ChatGPT Search, Gemini and the rest actually looked up, merged with the People also ask questions on the last Google page of each tracked keyword, one row per text. `source=ai` keeps only the engines' searches and `source=google` only the questions; with no `source` both come back, as in the app.\n\nFilters compose with AND: `report_id` (repeat for several), `scheduled_report_id`, `platform` (repeat for several engines), `date_from`, `date_to`, `category` (repeat for several) and `search` (a substring of the query, or of a question's keyword). The Google questions come from each keyword's last rank check, so only `search` narrows them, and `platform` leaves them out. Offset paginated via `limit` (1-500) and `offset`.","operationId":"list_fanouts_v1_brands__brand_id__fanouts_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Only searches containing this text (case-insensitive).","title":"Search"},"description":"Only searches containing this text (case-insensitive)."},{"name":"source","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"enum":["ai","google"],"type":"string"}},{"type":"null"}],"description":"`ai`: the engines' searches. `google`: the People also ask questions of the tracked keywords. Repeat the parameter for several; omit it for both.","title":"Source"},"description":"`ai`: the engines' searches. `google`: the People also ask questions of the tracked keywords. Repeat the parameter for several; omit it for both."},{"name":"sort","in":"query","required":false,"schema":{"enum":["times","keywords","prompts","last_seen"],"type":"string","description":"`times` (default): most run first. `keywords`: the questions of the most tracked keywords first. `prompts`: the searches of the most prompts first. `last_seen`: newest first.","default":"times","title":"Sort"},"description":"`times` (default): most run first. `keywords`: the questions of the most tracked keywords first. `prompts`: the searches of the most prompts first. `last_seen`: newest first."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Searches per page (1-500, default 100).","default":100,"title":"Limit"},"description":"Searches per page (1-500, default 100)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Searches to skip from the start.","default":0,"title":"Offset"},"description":"Searches to skip from the start."},{"name":"report_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Only these reports (UUIDs); repeat the parameter for several.","title":"Report Id"},"description":"Only these reports (UUIDs); repeat the parameter for several."},{"name":"report_scope","in":"query","required":false,"schema":{"anyOf":[{"const":"all","type":"string"},{"type":"null"}],"description":"`all` for every completed report of the brand, in place of naming each one; the other filters still apply.","title":"Report Scope"},"description":"`all` for every completed report of the brand, in place of naming each one; the other filters still apply."},{"name":"scheduled_report_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only the runs of this Scheduled Report (UUID).","title":"Scheduled Report Id"},"description":"Only the runs of this Scheduled Report (UUID)."},{"name":"tracker_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":200},{"type":"null"}],"description":"Only the runs of these trackers (a report's `tracker_id`; a scheduled report's id is its tracker's); repeat the parameter for several.","title":"Tracker Id"},"description":"Only the runs of these trackers (a report's `tracker_id`; a scheduled report's id is its tracker's); repeat the parameter for several."},{"name":"market_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":200},{"type":"null"}],"description":"Only the runs in these markets (a report's `market_id`, a region config's `id`); repeat the parameter for several.","title":"Market Id"},"description":"Only the runs in these markets (a report's `market_id`, a region config's `id`); repeat the parameter for several."},{"name":"place","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","minLength":1,"maxLength":300},"maxItems":200},{"type":"null"}],"description":"Only the runs in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake, `australia|emerald|victoria`), across every tracker; repeat the parameter for several.","title":"Place"},"description":"Only the runs in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake, `australia|emerald|victoria`), across every tracker; repeat the parameter for several."},{"name":"scope","in":"query","required":false,"schema":{"anyOf":[{"enum":["default","all"],"type":"string"},{"type":"null"}],"description":"`default` reads what the app opens on (every scheduled report's runs plus the newest one-off reports) and takes no other report, tracker, market or place filter; `all` reads every completed report of the brand.","title":"Scope"},"description":"`default` reads what the app opens on (every scheduled report's runs plus the newest one-off reports) and takes no other report, tracker, market or place filter; `all` reads every completed report of the brand."},{"name":"platform","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"enum":["chatgpt","chatgpt_search","perplexity","ai_overviews","claude","claude_search","gemini","grok","muse"],"type":"string"}},{"type":"null"}],"description":"Only answers from these engines; repeat the parameter for several.","title":"Platform"},"description":"Only answers from these engines; repeat the parameter for several."},{"name":"date_from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only answers from this moment on (ISO-8601).","title":"Date From"},"description":"Only answers from this moment on (ISO-8601)."},{"name":"date_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only answers before this moment, exclusive (ISO-8601); not before `date_from`.","title":"Date To"},"description":"Only answers before this moment, exclusive (ISO-8601); not before `date_from`."},{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","maxLength":200},"maxItems":50},{"type":"null"}],"description":"Only answers to prompts of these categories; repeat the parameter for several.","title":"Category"},"description":"Only answers to prompts of these categories; repeat the parameter for several."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned fan-out searches","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FanoutList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:reports","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/fanouts/prompts":{"get":{"tags":["Fanouts"],"summary":"List the prompts behind a fan-out search","description":"The prompts whose answers made the engines run one search, one row per prompt and engine, most frequent first. `query` is a `query` from `GET /v1/brands/{brand_id}/fanouts`; case and spacing do not matter.\n\nTakes the same filters as the list: `report_id`, `scheduled_report_id`, `platform`, `date_from`, `date_to` and `category` (repeat for several). Returns every row: one search is bounded by the prompts that ran it.","operationId":"list_fanout_prompts_v1_brands__brand_id__fanouts_prompts_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"query","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":500,"description":"The search, as the list returns it.","title":"Query"},"description":"The search, as the list returns it."},{"name":"report_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Only these reports (UUIDs); repeat the parameter for several.","title":"Report Id"},"description":"Only these reports (UUIDs); repeat the parameter for several."},{"name":"report_scope","in":"query","required":false,"schema":{"anyOf":[{"const":"all","type":"string"},{"type":"null"}],"description":"`all` for every completed report of the brand, in place of naming each one; the other filters still apply.","title":"Report Scope"},"description":"`all` for every completed report of the brand, in place of naming each one; the other filters still apply."},{"name":"scheduled_report_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only the runs of this Scheduled Report (UUID).","title":"Scheduled Report Id"},"description":"Only the runs of this Scheduled Report (UUID)."},{"name":"tracker_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":200},{"type":"null"}],"description":"Only the runs of these trackers (a report's `tracker_id`; a scheduled report's id is its tracker's); repeat the parameter for several.","title":"Tracker Id"},"description":"Only the runs of these trackers (a report's `tracker_id`; a scheduled report's id is its tracker's); repeat the parameter for several."},{"name":"market_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":200},{"type":"null"}],"description":"Only the runs in these markets (a report's `market_id`, a region config's `id`); repeat the parameter for several.","title":"Market Id"},"description":"Only the runs in these markets (a report's `market_id`, a region config's `id`); repeat the parameter for several."},{"name":"place","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","minLength":1,"maxLength":300},"maxItems":200},{"type":"null"}],"description":"Only the runs in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake, `australia|emerald|victoria`), across every tracker; repeat the parameter for several.","title":"Place"},"description":"Only the runs in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake, `australia|emerald|victoria`), across every tracker; repeat the parameter for several."},{"name":"scope","in":"query","required":false,"schema":{"anyOf":[{"enum":["default","all"],"type":"string"},{"type":"null"}],"description":"`default` reads what the app opens on (every scheduled report's runs plus the newest one-off reports) and takes no other report, tracker, market or place filter; `all` reads every completed report of the brand.","title":"Scope"},"description":"`default` reads what the app opens on (every scheduled report's runs plus the newest one-off reports) and takes no other report, tracker, market or place filter; `all` reads every completed report of the brand."},{"name":"platform","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"enum":["chatgpt","chatgpt_search","perplexity","ai_overviews","claude","claude_search","gemini","grok","muse"],"type":"string"}},{"type":"null"}],"description":"Only answers from these engines; repeat the parameter for several.","title":"Platform"},"description":"Only answers from these engines; repeat the parameter for several."},{"name":"date_from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only answers from this moment on (ISO-8601).","title":"Date From"},"description":"Only answers from this moment on (ISO-8601)."},{"name":"date_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only answers before this moment, exclusive (ISO-8601); not before `date_from`.","title":"Date To"},"description":"Only answers before this moment, exclusive (ISO-8601); not before `date_from`."},{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","maxLength":200},"maxItems":50},{"type":"null"}],"description":"Only answers to prompts of these categories; repeat the parameter for several.","title":"Category"},"description":"Only answers to prompts of these categories; repeat the parameter for several."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned the prompts behind a fan-out search","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FanoutPromptList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:reports","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/exports":{"post":{"tags":["Exports"],"summary":"Export a brand's history","description":"Start an export of the brand's whole citation and answer history (or the window and reports the filters name) into downloadable files, and return it at once (`202 Accepted`, with its URL in `Location`). Use this instead of paging `GET .../citations`, `.../citations/pages` or `.../prompts/answers` through a brand's history: the export reads it in the background, in batches that never compete with live reads.\n\nWorkflow:\n1. `POST /v1/brands/{brand_id}/exports`: returns the export, `status: queued`.\n2. `GET /v1/brands/{brand_id}/exports/{export_id}`: poll every few seconds until `status` is `completed`; `progress_pct` says how far it got.\n3. Download each `results[].files[].url` before `links_expire_at` (15 minutes); read the export again for fresh links. The files are deleted 24 hours after the export completes.\n\nEach file is gzipped NDJSON, one JSON object per line, oldest answer first. A `citations` line is one URL one answer cited: `answer_id`, `created_at`, `platform`, `position`, `url`, `domain`, `title`, `prompt_text`, `prompt_hash`, `category` (the prompt's category in that run), `report_id`, `scheduled_report_id` and `tracker_id`. An `answers` line is one engine answer: `id`, `created_at`, `platform`, `model_version`, `prompt_text`, `prompt_hash`, `category`, `brand_appears`, `rank`, `response` (the full text), `businesses_categorized`, `citation_count`, `fanouts` (the web searches the engine ran for it), `report_id`, `report_name`, `scheduled_report_id` and `tracker_id`. Every line also carries its market: `market_id`, `place_key` (`country|city`, or `country|city|region` for a town keyed apart from its namesake; the `place` filter), `country`, `city` and `language`. Filter with `market_id` and `place` to export one market or place. Only answers of completed reports count.\n\nFilters compose with AND and mirror the list endpoints: `report_id` (several), `scheduled_report_id`, `platform` (several), `date_from` and `date_to`. `datasets` defaults to both.\n\nOne export per brand runs at a time for a caller: asking again with the same body returns the one running (or resumes a `failed` one where it stopped), and a different body while one runs is `409 conflict` with its `export_id`. The `citations` dataset also needs the `read:citations` scope. Free: no credits.","operationId":"create_data_export_v1_brands__brand_id__exports_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDataExportRequest"}}}},"responses":{"202":{"description":"Export queued, or the same export already running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataExport"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:reports","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/exports/{export_id}":{"get":{"tags":["Exports"],"summary":"Retrieve an export","description":"The export's `status`, `progress_pct` and rows so far, and once `completed` a signed link per file, valid for 15 minutes. Exports are the caller's own: another user's export id is `404 not_found`.","operationId":"get_data_export_v1_brands__brand_id__exports__export_id__get","parameters":[{"name":"export_id","in":"path","required":true,"schema":{"type":"string","description":"The export id `POST .../exports` returned.","title":"Export Id"},"description":"The export id `POST .../exports` returned."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned an export","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataExport"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:reports","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/prompt-discoveries":{"get":{"tags":["Prompt discovery"],"summary":"List discovered prompts","description":"Questions and keywords worth tracking from one free `source`: `google_demand` (the site's Search Console queries of the last 28 days joined with the keywords its domain ranks for, one row per query, Search Console's order first; `origin` says which side reports it), `search_console` (every query the site gets impressions for, most impressions first, read live from Google and kept five minutes; on a very large site the first read can take a minute or more, and a retry a minute later is served from the kept copy), `ranking` (the keywords the brand's domain ranks for in Google, from the stored overview), `competitors` (prompts whose answers name a competitor and not the brand, the most such answers first), `fanouts` (the web searches the engines ran) or `copilot` (the grounding queries in the queries file of the newest period the brand uploaded from Bing's AI Performance, the most citations of its site first, with `citations` and Bing's `intent`). Every row carries `tracked_as_prompt` and `tracked_as_keyword`, so what is already tracked can be skipped. `note` says why a source, or half of `google_demand`, is empty and how to fill it. `search_console` and `copilot` also need the `read:analytics` scope, `ranking` the `read:seo` scope and `google_demand` both.\n\nOffset paginated via `limit` (1-100) and `offset`. Research and page reads cost credits: `POST` on this path.","operationId":"list_prompt_discoveries_v1_brands__brand_id__prompt_discoveries_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"source","in":"query","required":true,"schema":{"enum":["google_demand","search_console","ranking","competitors","fanouts","copilot"],"type":"string","description":"The source to read.","title":"Source"},"description":"The source to read."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Rows per page (1-100, default 25).","default":25,"title":"Limit"},"description":"Rows per page (1-100, default 25)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip from the start.","default":0,"title":"Offset"},"description":"Rows to skip from the start."},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"`google_demand`, `competitors`, `fanouts` and `copilot`: case-insensitive match on the text.","title":"Search"},"description":"`google_demand`, `competitors`, `fanouts` and `copilot`: case-insensitive match on the text."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned discovered prompts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiscoveredPromptList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:reports","x-rankprompt-cost":{"request_units":2,"credits":0}},"post":{"tags":["Prompt discovery"],"summary":"Discover prompts from a seed or a page","description":"`research`: keyword ideas around `seed` in the brand's market, 1 credit and free when the same seed and `mode` were researched in the last 24 hours. `page`: read `url` (the brand's page or a competitor's) and write the prompts people ask an AI assistant about what it offers, `organic` or `commercial`, 1 credit and free when the same page, country and intent were read in the last 24 hours. Every row carries `tracked_as_prompt` and `tracked_as_keyword`, so what is already tracked can be skipped. Returns every row in one page.","operationId":"create_prompt_discovery_v1_brands__brand_id__prompt_discoveries_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromptDiscoveryCreate"}}}},"responses":{"200":{"description":"Discover prompts from a seed or a page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiscoveredPromptList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"402":{"description":"Not enough credits to complete this operation","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"insufficient_credits","message":"Not enough credits to complete this operation"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:seo","x-rankprompt-cost":{"request_units":2,"credits":0},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}}},"/v1/jobs/{job_id}":{"get":{"tags":["Jobs"],"summary":"Poll a job","description":"Poll an async job's progress and read its `status`, `progress_pct`, and (when terminal) `result` or `error`.\n\nUse after any endpoint that returns `202 Accepted` with a `job_id` (brand-facts research, report runs, schedule executions).\n\nReturns `404 not_found` for unknown, expired (1h TTL), or non-owned jobs (symmetric with `DELETE /v1/jobs/{job_id}`) to avoid leaking existence.","operationId":"get_job_v1_jobs__job_id__get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","description":"Job identifier returned by an async-creating endpoint.","title":"Job Id"},"description":"Job identifier returned by an async-creating endpoint."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Poll a job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:jobs","x-rankprompt-cost":{"request_units":1,"credits":0}},"delete":{"tags":["Jobs"],"summary":"Cancel a job","description":"Signal cancellation of an in-flight job.\n\nBest-effort: a run already under way may still settle to `completed` or `failed`, and credits already consumed are **not** refunded.\n\nAlready-terminal jobs (`completed`, `failed`, `cancelled`) return `204` as a no-op. Returns `404` for unknown or non-owned jobs.","operationId":"cancel_job_v1_jobs__job_id__delete","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","description":"Job identifier returned by an async-creating endpoint.","title":"Job Id"},"description":"Job identifier returned by an async-creating endpoint."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"204":{"description":"Cancellation signal recorded (or job already terminal).","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:jobs","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/jobs":{"get":{"tags":["Jobs"],"summary":"List recent jobs","description":"List jobs owned by the principal, newest first. Jobs are retained for 1 hour; older ones fall out of the window.\n\nCursor-paginated via `?limit=` (1-100, default 20) and `?cursor=`. Filter with `?status=` (`pending`, `processing`, `completed`, `failed`, `cancelled`).","operationId":"list_jobs_v1_jobs_get","parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"enum":["pending","processing","completed","failed","cancelled"],"type":"string"},{"type":"null"}],"description":"Filter to a single lifecycle status.","title":"Status"},"description":"Filter to a single lifecycle status."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Page size (default 20, max 100).","default":20,"title":"Limit"},"description":"Page size (default 20, max 100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Continuation token from a previous response's `next_cursor`.","title":"Cursor"},"description":"Continuation token from a previous response's `next_cursor`."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned recent jobs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:jobs","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/page-audit":{"post":{"tags":["Page audit"],"summary":"Audit one or more pages","description":"Audit public pages against SEO and AEO best practices and return, per page, an overall score plus concrete recommendations.\n\nProvide exactly one of `url` (a single page), `urls` (several), or `sitemap` (a sitemap.xml or bare domain whose first pages are audited). Domain-level checks (robots.txt, sitemap, /llms.txt, SSL) are fetched once per domain and reused across that domain's pages.\n\nPer-page checks include `<title>` / meta description length, a single `<h1>`, Schema.org JSON-LD, canonical, Open Graph + Twitter cards, image alt-text, indexability (noindex), and content freshness.\n\n**Pricing:** 1 credit per page that is successfully audited, so a batch costs up to one credit per URL. `x-rankprompt-cost` and `?dry_run=true` report the single-page cost; multiply by the number of URLs you send. A page that cannot be fetched is not charged. `credits_charged` reports the total spent. Pass a `request_id` (unique per intended billable audit) to make a retried per-URL charge idempotent; omit it and every call is charged.\n\nCredits come from the account the key acts in. A key created in a team account needs an editor seat over every brand of that account, or the call is refused with `403 forbidden`.\n\n**Security:** only `https` URLs on public hosts are accepted; internal hosts, loopback and cloud-metadata addresses are rejected, including on redirects.\n\nRate limited more tightly than most endpoints; the exact limit is published as `x-rankprompt-rate-limit` on this operation.","operationId":"audit_pages_v1_page_audit_post","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageAuditRequest"}}}},"responses":{"200":{"description":"Audit one or more pages","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageAuditResult"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"402":{"description":"Not enough credits to complete this operation","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"insufficient_credits","message":"Not enough credits to complete this operation"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:audit","x-rankprompt-cost":{"request_units":3,"credits":1},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}}},"/v1/brands/{brand_id}/webhooks":{"get":{"tags":["Webhooks"],"summary":"List webhook endpoints","description":"List a brand's webhook endpoints (newest first). Secrets are never returned.","operationId":"list_webhooks_v1_brands__brand_id__webhooks_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned webhook endpoints","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:webhooks","x-rankprompt-cost":{"request_units":1,"credits":0}},"post":{"tags":["Webhooks"],"summary":"Create a webhook endpoint","description":"Subscribe an HTTPS URL to one or more events. The response includes the signing `secret` **exactly once** (store it now). Max 5 active endpoints per brand. The URL must be a public HTTPS address (private/loopback targets are rejected).","operationId":"create_webhook_v1_brands__brand_id__webhooks_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookCreate"}}}},"responses":{"201":{"description":"Webhook created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookWithSecret"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:webhooks","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/webhooks/{webhook_id}":{"get":{"tags":["Webhooks"],"summary":"Retrieve a webhook endpoint","description":"Return a single webhook endpoint by id. Secrets are never returned.","operationId":"get_webhook_v1_brands__brand_id__webhooks__webhook_id__get","parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","description":"Webhook endpoint id (whk_…).","title":"Webhook Id"},"description":"Webhook endpoint id (whk_…)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned a webhook endpoint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:webhooks","x-rankprompt-cost":{"request_units":1,"credits":0}},"patch":{"tags":["Webhooks"],"summary":"Update a webhook endpoint","description":"Partial update of `url`, `events`, `description`, `is_active` or `destination_type`. Set `is_active: true` to re-enable. `events` replaces the whole set, article events included.","operationId":"update_webhook_v1_brands__brand_id__webhooks__webhook_id__patch","parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","description":"Webhook endpoint id (whk_…).","title":"Webhook Id"},"description":"Webhook endpoint id (whk_…)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookUpdate"}}}},"responses":{"200":{"description":"Updated a webhook endpoint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:webhooks","x-rankprompt-cost":{"request_units":1,"credits":0}},"delete":{"tags":["Webhooks"],"summary":"Delete a webhook endpoint","description":"Delete a webhook endpoint and its delivery history. Irreversible.","operationId":"delete_webhook_v1_brands__brand_id__webhooks__webhook_id__delete","parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","description":"Webhook endpoint id (whk_…).","title":"Webhook Id"},"description":"Webhook endpoint id (whk_…)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"204":{"description":"Webhook deleted.","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:webhooks","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/webhooks/{webhook_id}/secret-rotations":{"post":{"tags":["Webhooks"],"summary":"Rotate the signing secret","description":"Generate a new signing secret, returned **once**. The previous secret keeps signing deliveries (as `v0`) for a 24h overlap so you can roll your verifier with no downtime.","operationId":"rotate_webhook_secret_v1_brands__brand_id__webhooks__webhook_id__secret_rotations_post","parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","description":"Webhook endpoint id (whk_…).","title":"Webhook Id"},"description":"Webhook endpoint id (whk_…)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"201":{"description":"Secret rotated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSecretRotated"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:webhooks","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/webhooks/{webhook_id}/deliveries":{"get":{"tags":["Webhooks"],"summary":"List recent deliveries","description":"Cursor-paginated delivery log for an endpoint (newest first). A debug aid.","operationId":"list_webhook_deliveries_v1_brands__brand_id__webhooks__webhook_id__deliveries_get","parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","description":"Webhook endpoint id (whk_…).","title":"Webhook Id"},"description":"Webhook endpoint id (whk_…)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Page size (default 20, max 100).","default":20,"title":"Limit"},"description":"Page size (default 20, max 100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Continuation token from a previous response's `next_cursor`.","title":"Cursor"},"description":"Continuation token from a previous response's `next_cursor`."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned recent deliveries","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeliveryList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:webhooks","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/webhooks/{webhook_id}/deliveries/{delivery_id}/replays":{"post":{"tags":["Webhooks"],"summary":"Replay a delivery","description":"Re-enqueue a past delivery for another attempt, with its event id and body. Returns the new pending delivery id.","operationId":"replay_webhook_delivery_v1_brands__brand_id__webhooks__webhook_id__deliveries__delivery_id__replays_post","parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","description":"Webhook endpoint id (whk_…).","title":"Webhook Id"},"description":"Webhook endpoint id (whk_…)."},{"name":"delivery_id","in":"path","required":true,"schema":{"type":"string","description":"Delivery UUID to replay.","title":"Delivery Id"},"description":"Delivery UUID to replay."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"202":{"description":"Delivery re-enqueued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeliveryReplayed"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:webhooks","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/webhooks/{webhook_id}/test-deliveries":{"post":{"tags":["Webhooks"],"summary":"Send a test delivery","description":"Send a sample of one event the endpoint subscribes to, right now and through the same signer and client as a real delivery. The sample carries `test: true` and an `evt_test_` id; the attempt is logged with `is_test` and never counts toward auto-disable. Answers with what the endpoint returned. At most 10 test deliveries a minute per endpoint, then `429 rate_limit_exceeded`.","operationId":"create_test_delivery_v1_brands__brand_id__webhooks__webhook_id__test_deliveries_post","parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","description":"Webhook endpoint id (whk_…).","title":"Webhook Id"},"description":"Webhook endpoint id (whk_…)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookTestDeliveryRequest"}}}},"responses":{"201":{"description":"Sample sent; the body says how the endpoint answered.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookTestDelivery"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:webhooks","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/reports/{report_id}/ai-suggestions":{"post":{"tags":["Reports"],"summary":"Generate AI suggestion","description":"Generate an AI suggestion for a completed report and persist the tasks it recommends. Returns a cached suggestion when one already exists unless `force_regenerate=true`. Debits one product credit to the calling key's user on generation, except for a brand's first suggestion, which is free (once per brand). `force_regenerate=true` always debits a credit.","operationId":"generate_ai_suggestion_v1_reports__report_id__ai_suggestions_post","parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"string","description":"Report UUID.","title":"Report Id"},"description":"Report UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiSuggestionRequest"}}}},"responses":{"200":{"description":"Generate AI suggestion","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiSuggestionResult"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"402":{"description":"Not enough credits to complete this operation","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"insufficient_credits","message":"Not enough credits to complete this operation"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:reports","x-rankprompt-cost":{"request_units":5,"credits":1},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}}},"/v1/brands/{brand_id}/competitors":{"get":{"tags":["Competitors"],"summary":"List competitors","description":"List the brand's cross-report competitor directory (canonical entities discovered across reports). Newest activity is surfaced by `mention_count` / `report_count`.\n\nFilters compose with AND: `category` (repeat it for several), `tag` (exact, case-sensitive label) and `search` (case-insensitive match on name). `facets` counts the entities per category and per tag, each under every filter but its own, so a count is what that filter value would list. Limit-bounded via `limit` (1-100) and `offset`; this endpoint is not cursor-paginated.","operationId":"list_competitors_v1_brands__brand_id__competitors_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Number of competitors to return (1-100, default 50).","default":50,"title":"Limit"},"description":"Number of competitors to return (1-100, default 50)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of competitors to skip from the start of the directory.","default":0,"title":"Offset"},"description":"Number of competitors to skip from the start of the directory."},{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"enum":["direct_competitor","indirect_competitor","ai_platform","publisher","other"],"type":"string"}},{"type":"null"}],"description":"Only entities in these categories; repeat for several (`category=ai_platform&category=publisher`).","title":"Category"},"description":"Only entities in these categories; repeat for several (`category=ai_platform&category=publisher`)."},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Case-insensitive substring match on the competitor name.","title":"Search"},"description":"Case-insensitive substring match on the competitor name."},{"name":"tag","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}],"description":"Only entities carrying this label.","title":"Tag"},"description":"Only entities carrying this label."},{"name":"order_by","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(mention_count|report_count|last_seen_at|canonical_name)$"},{"type":"null"}],"description":"Sort column: `mention_count` (default), `report_count`, `last_seen_at`, or `canonical_name`.","title":"Order By"},"description":"Sort column: `mention_count` (default), `report_count`, `last_seen_at`, or `canonical_name`."},{"name":"order_dir","in":"query","required":false,"schema":{"type":"string","pattern":"^(asc|desc)$","description":"Sort direction (`asc` or `desc`, default `desc`).","default":"desc","title":"Order Dir"},"description":"Sort direction (`asc` or `desc`, default `desc`)."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned competitors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompetitorList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:competitors","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/competitors/summary":{"get":{"tags":["Competitors"],"summary":"Competitor share of voice","description":"Share of voice of the brand and its competitors, the numbers the Competitors page shows under the same filters: per entity the answers naming it, its percent of all mentions, its change from the older half of the runs to the newer, its engines, whether it is new and how many answers named it without the brand. Competitors are read through the directory: an alias counts under its competitor's name and a removed competitor is left out.\n\nThe period defaults to the 30 days before `date_to`, and `date_to` to now. With no `tracker_id`, `market_id`, `place` or `scheduled_report_id` it reads what the page opens on (`scope=default`); `scope=all` reads every completed report. `platform` keeps answers from those engines. Offset-paginated: the brand first, then the competitors most mentioned first; shares are over every entity under the filters, not only the page.","operationId":"competitors_summary_v1_brands__brand_id__competitors_summary_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"date_from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Start of the period, inclusive (ISO-8601). Defaults to 30 days before `date_to`.","title":"Date From"},"description":"Start of the period, inclusive (ISO-8601). Defaults to 30 days before `date_to`."},{"name":"date_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"End of the period, exclusive (ISO-8601). Defaults to now.","title":"Date To"},"description":"End of the period, exclusive (ISO-8601). Defaults to now."},{"name":"scheduled_report_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only the runs of this Scheduled Report (UUID).","title":"Scheduled Report Id"},"description":"Only the runs of this Scheduled Report (UUID)."},{"name":"tracker_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":200},{"type":"null"}],"description":"Only the runs of these trackers (a report's `tracker_id`; a scheduled report's id is its tracker's); repeat the parameter for several.","title":"Tracker Id"},"description":"Only the runs of these trackers (a report's `tracker_id`; a scheduled report's id is its tracker's); repeat the parameter for several."},{"name":"market_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":200},{"type":"null"}],"description":"Only the runs in these markets (a report's `market_id`, a region config's `id`); repeat the parameter for several.","title":"Market Id"},"description":"Only the runs in these markets (a report's `market_id`, a region config's `id`); repeat the parameter for several."},{"name":"place","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","minLength":1,"maxLength":300},"maxItems":200},{"type":"null"}],"description":"Only the runs in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake, `australia|emerald|victoria`), across every tracker; repeat the parameter for several.","title":"Place"},"description":"Only the runs in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake, `australia|emerald|victoria`), across every tracker; repeat the parameter for several."},{"name":"scope","in":"query","required":false,"schema":{"anyOf":[{"enum":["default","all"],"type":"string"},{"type":"null"}],"description":"`default` (what the page opens on: every scheduled report's runs plus the newest one-off reports, and the default when no tracker, market, place or schedule is given) or `all` (every completed report). Takes no tracker, market, place or schedule filter.","title":"Scope"},"description":"`default` (what the page opens on: every scheduled report's runs plus the newest one-off reports, and the default when no tracker, market, place or schedule is given) or `all` (every completed report). Takes no tracker, market, place or schedule filter."},{"name":"platform","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"enum":["chatgpt","chatgpt_search","perplexity","ai_overviews","claude","claude_search","gemini","grok","muse"],"type":"string"}},{"type":"null"}],"description":"Only answers from these engines; repeat the parameter for several.","title":"Platform"},"description":"Only answers from these engines; repeat the parameter for several."},{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"enum":["direct_competitor","indirect_competitor","ai_platform","publisher","other"],"type":"string"}},{"type":"null"}],"description":"The relations counted; repeat for several (`category=direct_competitor&category=publisher`). Direct and indirect competitors when left out.","title":"Category"},"description":"The relations counted; repeat for several (`category=direct_competitor&category=publisher`). Direct and indirect competitors when left out."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Page size (1-500).","default":100,"title":"Limit"},"description":"Page size (1-500)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip.","default":0,"title":"Offset"},"description":"Rows to skip."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Competitor share of voice","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompetitorSummary"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:competitors","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/competitors/duplicates":{"get":{"tags":["Competitors"],"summary":"List likely duplicate competitors","description":"Entities of the directory that look like one company, grouped: first those that share a domain (`reason=domain`), then those whose names match once case, accents and company suffixes such as Inc or GmbH go (`reason=name`). A set of entities appears in one group at most.\n\nMerge a group with `POST /v1/brands/{brand_id}/competitors/merges`.\n\nOffset-paginated: the groups are found from the directory at read time, domain groups first, each reason in the order of its most mentioned entity.","operationId":"list_competitor_duplicates_v1_brands__brand_id__competitors_duplicates_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Groups per page (1-100).","default":20,"title":"Limit"},"description":"Groups per page (1-100)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Groups to skip.","default":0,"title":"Offset"},"description":"Groups to skip."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned likely duplicate competitors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompetitorDuplicates"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:competitors","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/competitors/{competitor_id}":{"patch":{"tags":["Competitors"],"summary":"Update a competitor","description":"Curate a competitor entity: rename it, reclassify its `category`, set its `website` or label it with `tags`. Only the fields you send change. A category change also updates how past reports count it. Setting `category` to `my_brand` says the entity is the brand itself: its names become brand aliases, past reports are recalculated in the background and it leaves the directory.","operationId":"update_competitor_v1_brands__brand_id__competitors__competitor_id__patch","parameters":[{"name":"competitor_id","in":"path","required":true,"schema":{"type":"string","description":"Competitor id (UUID).","title":"Competitor Id"},"description":"Competitor id (UUID)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompetitorUpdate"}}}},"responses":{"200":{"description":"Updated a competitor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Competitor"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:competitors","x-rankprompt-cost":{"request_units":1,"credits":0}},"delete":{"tags":["Competitors"],"summary":"Delete a competitor","description":"Remove a competitor entity and strip its mentions from past reports (done in the background). Use `merge` instead when the entity is a duplicate you want to keep counting under another name.","operationId":"delete_competitor_v1_brands__brand_id__competitors__competitor_id__delete","parameters":[{"name":"competitor_id","in":"path","required":true,"schema":{"type":"string","description":"Competitor id (UUID).","title":"Competitor Id"},"description":"Competitor id (UUID)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"204":{"description":"Competitor deleted.","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:competitors","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/competitors/merges":{"post":{"tags":["Competitors"],"summary":"Merge duplicate competitors","description":"Merge one or more duplicate entities into a single canonical competitor. Their mentions are re-attributed to the winner across past reports in the background, so scores may take a moment to reflect the merge.","operationId":"merge_competitors_v1_brands__brand_id__competitors_merges_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompetitorMerge"}}}},"responses":{"202":{"description":"Merge duplicate competitors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompetitorMergeResult"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:competitors","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/content-opportunities":{"get":{"tags":["Content"],"summary":"List content opportunities","description":"Report-driven content ideas for the brand: prompts where the brand is absent from AI answers (`missed_prompt`) plus competitors cited in its place (`competitor`), each pre-classified to a content format and pre-filled with topic, keywords, and context.\n\nRanked with not-yet-covered opportunities first, then by impact. Filter with `kind`, `place` and `search` (every word must appear in the title, topic, keywords or competitor, ignoring case and accents), order with `sort` and `order`, and page with `limit` (1-50, default 24) and `offset` while `has_more`; `total` is the size of the filtered set. Each row carries `metrics` with the search volume, Google and AI difficulty and Search Console numbers behind its score.\n\nThe set is computed on the first read of a brand and stored; `summary.refresh_available` says when newer data would change it.","operationId":"list_content_opportunities_v1_brands__brand_id__content_opportunities_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"description":"Number of opportunities to return (1-50, default 24).","default":24,"title":"Limit"},"description":"Number of opportunities to return (1-50, default 24)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Opportunities to skip, for the next page.","default":0,"title":"Offset"},"description":"Opportunities to skip, for the next page."},{"name":"sort","in":"query","required":false,"schema":{"enum":["score","title","source"],"type":"string","description":"`score` with `order=desc` ranks uncovered opportunities first, then by impact.","default":"score","title":"Sort"},"description":"`score` with `order=desc` ranks uncovered opportunities first, then by impact."},{"name":"order","in":"query","required":false,"schema":{"enum":["asc","desc"],"type":"string","description":"Sort direction.","default":"desc","title":"Order"},"description":"Sort direction."},{"name":"kind","in":"query","required":false,"schema":{"anyOf":[{"enum":["missed_prompt","competitor","keyword_gap","search_console","tracked_keyword"],"type":"string"},{"type":"null"}],"description":"Only opportunities of this kind.","title":"Kind"},"description":"Only opportunities of this kind."},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Only opportunities whose title, topic, keywords or competitor hold every word.","title":"Search"},"description":"Only opportunities whose title, topic, keywords or competitor hold every word."},{"name":"content_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"description":"Only opportunities suggesting this format (e.g. `ranked_list`).","title":"Content Type"},"description":"Only opportunities suggesting this format (e.g. `ranked_list`)."},{"name":"place","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","minLength":1,"maxLength":300},"maxItems":200},{"type":"null"}],"description":"Only opportunities whose prompts were asked in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake): a row's `places[].place_key`. Leaves out the brand wide sources (keyword gap, Search Console, tracked keywords). Repeat the parameter for several.","title":"Place"},"description":"Only opportunities whose prompts were asked in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake): a row's `places[].place_key`. Leaves out the brand wide sources (keyword gap, Search Console, tracked keywords). Repeat the parameter for several."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned content opportunities","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentOpportunityList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:content","x-rankprompt-cost":{"request_units":3,"credits":0}}},"/v1/brands/{brand_id}/content-opportunities/refreshes":{"post":{"tags":["Content"],"summary":"Recompute the opportunities","description":"Work the opportunities out again from what the account already holds: the reports, the citations, the tracked keywords and Search Console. No vendor calls and no credits, so run it after a report finishes or after tracking new keywords. The read serves the stored set, and its `summary.refresh_available` says when this would change it.\n\nTakes the same filters and paging as the read, and answers with the recomputed page.","operationId":"refresh_content_opportunities_v1_brands__brand_id__content_opportunities_refreshes_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"description":"How many to return.","default":24,"title":"Limit"},"description":"How many to return."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Opportunities to skip, for the next page.","default":0,"title":"Offset"},"description":"Opportunities to skip, for the next page."},{"name":"sort","in":"query","required":false,"schema":{"enum":["score","title","source"],"type":"string","description":"How to order them.","default":"score","title":"Sort"},"description":"How to order them."},{"name":"order","in":"query","required":false,"schema":{"enum":["asc","desc"],"type":"string","description":"Sort direction.","default":"desc","title":"Order"},"description":"Sort direction."},{"name":"kind","in":"query","required":false,"schema":{"anyOf":[{"enum":["missed_prompt","competitor","keyword_gap","search_console","tracked_keyword"],"type":"string"},{"type":"null"}],"description":"Only opportunities of this kind.","title":"Kind"},"description":"Only opportunities of this kind."},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Only opportunities whose title, topic, keywords or competitor hold every word.","title":"Search"},"description":"Only opportunities whose title, topic, keywords or competitor hold every word."},{"name":"content_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"description":"Only opportunities suggesting this format (e.g. `ranked_list`).","title":"Content Type"},"description":"Only opportunities suggesting this format (e.g. `ranked_list`)."},{"name":"place","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","minLength":1,"maxLength":300},"maxItems":200},{"type":"null"}],"description":"Only opportunities whose prompts were asked in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake): a row's `places[].place_key`. Leaves out the brand wide sources (keyword gap, Search Console, tracked keywords). Repeat the parameter for several.","title":"Place"},"description":"Only opportunities whose prompts were asked in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake): a row's `places[].place_key`. Leaves out the brand wide sources (keyword gap, Search Console, tracked keywords). Repeat the parameter for several."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Recompute the opportunities","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentOpportunityList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:content","x-rankprompt-cost":{"request_units":4,"credits":0}}},"/v1/brands/{brand_id}/content-preferences":{"get":{"tags":["Content"],"summary":"Read how this brand's articles are written","description":"The tone, writing style, image style, language and banned phrases the generator follows on every article of this brand, and `auto_interlink`, whether its related posts link back to each article that goes live. Null fields fall back to the brand's own language and the house defaults. Read it before generating: it is the difference between an article that sounds like the brand and one that does not.","operationId":"get_content_preferences_v1_brands__brand_id__content_preferences_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Read how this brand's articles are written","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentPreferences"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:content","x-rankprompt-cost":{"request_units":1,"credits":0}},"patch":{"tags":["Content"],"summary":"Set how this brand's articles are written","description":"Change what you send and leave the rest. `tone` and `writing_style` are free text the writer reads, so write them as you would tell a person: what to sound like, how long the paragraphs are, whether to use tables. `banned_phrases` are dropped whatever the topic. It applies to the next article, not to ones already written. A field sent as `null` clears it: `language: null` writes in the brand's market language again. `auto_interlink: true` applies the proposed links back to every article of the brand that goes live, on sites that can edit a post; other sites get a task. `recheck_source_prompts: true` runs each live article's source prompts again 14 and 28 days after it went live, charged like any run; it needs the brand owner on Starter.","operationId":"update_content_preferences_v1_brands__brand_id__content_preferences_patch","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentPreferencesUpdate"}}}},"responses":{"200":{"description":"Set how this brand's articles are written","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentPreferences"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:content","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/content-preferences/voice-extractions":{"post":{"tags":["Content"],"summary":"Learn this brand's voice from its site","description":"Read up to five of the brand's own posts and describe how it writes: persona, sentence length, reading level, formatting habits, recurring phrases, words to avoid and a writing style. It is saved as `voice_profile` and changes nothing else: copy what fits into `writing_style` and `banned_phrases` with the PATCH. The first time on a brand is free (the brand's first article also learns it); after that it costs 1 credit. A site with too little readable text answers `400`. Requires the brand owner on Starter or with an active API subscription.","operationId":"learn_brand_voice_v1_brands__brand_id__content_preferences_voice_extractions_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"201":{"description":"Learn this brand's voice from its site","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentPreferences"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"402":{"description":"Not enough credits to complete this operation","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"insufficient_credits","message":"Not enough credits to complete this operation"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:content","x-rankprompt-cost":{"request_units":3,"credits":0},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}}},"/v1/brands/{brand_id}/publish-targets":{"get":{"tags":["Content"],"summary":"List where articles can be published","description":"Everywhere this brand can publish: the blog Rank Prompt hosts for it, and each CMS connection it has. For a `cms_connection`, pass its `id` as `target_id` when publishing a brief; for the `hosted_site` only the `target_type` is needed, since it is resolved from the brand. An empty list means the brand has nowhere to publish yet: connect WordPress, or publish with `target_type=external` after putting the article live yourself.","operationId":"list_publish_targets_v1_brands__brand_id__publish_targets_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned where articles can be published","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublishTargetList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:cms","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/knowledge-base":{"get":{"tags":["Content"],"summary":"List the knowledge base","description":"The brand's knowledge base, newest first: notes, files and web pages its articles draw facts from, each with its `status`. Offset paginated. `q` matches the title or the page address.","operationId":"list_knowledge_items_v1_brands__brand_id__knowledge_base_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Text in the title or the source URL.","title":"Q"},"description":"Text in the title or the source URL."},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"enum":["processing","ready","failed"],"type":"string"},{"type":"null"}],"description":"Only this status.","title":"Status"},"description":"Only this status."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Items per call (1-100, default 50).","default":50,"title":"Limit"},"description":"Items per call (1-100, default 50)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Items to skip.","default":0,"title":"Offset"},"description":"Items to skip."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned the knowledge base","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeItemList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:content","x-rankprompt-cost":{"request_units":1,"credits":0}},"post":{"tags":["Content"],"summary":"Add a note or a web page","description":"`type: text` with `title` and `content` adds a note; `type: url` with `url` reads that page (and re-reads it every `refresh_interval_days` when set). It answers `processing` and becomes `ready` in the background, usually within a minute; poll the item. Files go to `POST .../knowledge-base/files`. Free on every plan: reading and splitting it costs no credits.","operationId":"create_knowledge_item_v1_brands__brand_id__knowledge_base_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeItemCreate"}}}},"responses":{"201":{"description":"Add a note or a web page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeItem"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:content","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/knowledge-base/search":{"get":{"tags":["Content"],"summary":"Search the knowledge base","description":"The passages an article about `q` would draw on, best first: full text and meaning combined, enabled items only. Only passages about `q` come back, so the list is empty when nothing in the knowledge base covers it. Use it to check what the brand's documents say before writing or briefing.","operationId":"search_knowledge_v1_brands__brand_id__knowledge_base_search_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":500,"description":"What the article is about.","title":"Q"},"description":"What the article is about."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":20,"minimum":1,"description":"Passages to return (1-20, default 8).","default":8,"title":"Limit"},"description":"Passages to return (1-20, default 8)."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Search the knowledge base","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeMatchList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:content","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/knowledge-base/files":{"post":{"tags":["Content"],"summary":"Upload a file to the knowledge base","description":"Multipart `file`: PDF (every page), Word (.docx), Markdown, plain text, CSV (each row with its headers) or an image (described by a vision model). Up to 10 MB. It answers `processing` and becomes `ready` in the background. Free on every plan: reading and splitting it costs no credits.","operationId":"upload_knowledge_file_v1_brands__brand_id__knowledge_base_files_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_upload_knowledge_file_v1_brands__brand_id__knowledge_base_files_post"}}}},"responses":{"201":{"description":"Upload a file to the knowledge base","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeItem"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:content","x-rankprompt-cost":{"request_units":3,"credits":0}}},"/v1/brands/{brand_id}/knowledge-base/{item_id}":{"patch":{"tags":["Content"],"summary":"Change a knowledge item","description":"Rename it, turn it off (`enabled: false` keeps it out of every article), tag it, date its facts or change how often its page is re-read. The text itself changes by adding the source again.","operationId":"update_knowledge_item_v1_brands__brand_id__knowledge_base__item_id__patch","parameters":[{"name":"item_id","in":"path","required":true,"schema":{"type":"string","description":"Knowledge item id (UUID), from the list.","title":"Item Id"},"description":"Knowledge item id (UUID), from the list."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeItemUpdate"}}}},"responses":{"200":{"description":"Change a knowledge item","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeItem"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:content","x-rankprompt-cost":{"request_units":1,"credits":0}},"delete":{"tags":["Content"],"summary":"Delete a knowledge item","description":"Delete the item, its passages and its stored file. Articles already written keep their text.","operationId":"delete_knowledge_item_v1_brands__brand_id__knowledge_base__item_id__delete","parameters":[{"name":"item_id","in":"path","required":true,"schema":{"type":"string","description":"Knowledge item id (UUID), from the list.","title":"Item Id"},"description":"Knowledge item id (UUID), from the list."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"204":{"description":"Deleted.","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:content","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/site-pages":{"get":{"tags":["Content"],"summary":"List the site index","description":"The brand's own pages as the site index holds them (its sitemap and its published articles, refreshed weekly): the pages articles link to internally. The most Google clicks first when Search Console is connected, then by title. Offset paginated: the order follows each Search Console fetch. `q` matches the address or the title.","operationId":"list_site_pages_v1_brands__brand_id__site_pages_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Text in the page address or title.","title":"Q"},"description":"Text in the page address or title."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Pages per call (1-100, default 50).","default":50,"title":"Limit"},"description":"Pages per call (1-100, default 50)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Pages to skip.","default":0,"title":"Offset"},"description":"Pages to skip."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned the site index","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SitePageList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:content","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/city-page-plan":{"get":{"tags":["Content"],"summary":"Read the city page plan","description":"The brand's city page plan: its services and cities with the evidence of each, and a page per city and per service in each city (and the `/locations` hub once a city page is ready), each a Website autopilot new page with the exact search it answers, its monthly volume and where it stands. A page is written only with two of three pieces of the city's own evidence (reviews that name the city, photos of work there, a fact of the city) and the brand facts the writer needs; it is written by a wave of Website autopilot new pages, in the app. A brand without a plan answers `404 not_found`.","operationId":"get_city_page_plan_v1_brands__brand_id__city_page_plan_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Read the city page plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CityPagePlan"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:content","x-rankprompt-cost":{"request_units":1,"credits":0}},"put":{"tags":["Content"],"summary":"Build or rebuild the city page plan","description":"Build the brand's city page plan from its services and the cities it serves, or build it again: the volume of each service and city search, charged like keyword research (1 credit per vendor batch; searches the shared cache knows are free), the pages the site's sitemap already has (`covered`), and a new page per city and service. A city kept keeps its evidence; a page a wave is writing is never touched, and the pages of cities left out are removed. A page is written only with two of three pieces of the city's own evidence (reviews that name the city, photos of work there, a fact of the city) and the brand facts the writer needs; it is written by a wave of Website autopilot new pages, in the app. Requires the brand owner on Starter or with an active API subscription: `403 brand_plan_required` otherwise.","operationId":"build_city_page_plan_v1_brands__brand_id__city_page_plan_put","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CityPagePlanBuild"}}}},"responses":{"200":{"description":"Build or rebuild the city page plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CityPagePlan"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"402":{"description":"Not enough credits to complete this operation","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"insufficient_credits","message":"Not enough credits to complete this operation"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:content","x-rankprompt-cost":{"request_units":5,"credits":0},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}}},"/v1/brands/{brand_id}/city-page-plan/evidence":{"post":{"tags":["Content"],"summary":"Set a city's evidence","description":"The owner's evidence of one city, for every page of the city: photos of work done there (images of the brand's media library, by id; another brand's answers `404 not_found`) and a fact of the city. A page that reaches two of three pieces becomes `ready`. Free. Requires the brand owner on Starter or with an active API subscription: `403 brand_plan_required` otherwise.","operationId":"set_city_evidence_v1_brands__brand_id__city_page_plan_evidence_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CityEvidence"}}}},"responses":{"200":{"description":"Set a city's evidence","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CityPagePlan"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:content","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/city-page-plan/shares":{"post":{"tags":["Content"],"summary":"Share the city page plan","description":"A public link to the brand's city page plan under the account's branding, for a client or a writer. A rebuilt plan gets a new link; sharing the same plan again refreshes it. `404 not_found` before a plan exists. Requires the brand owner on Starter or with an active API subscription: `403 brand_plan_required` otherwise.","operationId":"share_city_page_plan_v1_brands__brand_id__city_page_plan_shares_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CityPagePlanShareCreate"}}}},"responses":{"201":{"description":"Share the city page plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CityPagePlanShare"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:content","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/content-autopilot":{"get":{"tags":["Content"],"summary":"Read the brand's content autopilot","description":"The autopilot writes an article from the brand's content opportunities the day before each weekly slot and publishes it per its policy. `configured` is false while the brand never saved one; the values are then the defaults. `credits_per_month` says what the current settings cost the brand owner, `pause_reason` why it stopped on its own, and `last_run` what happened at the newest slot.","operationId":"get_content_autopilot_v1_brands__brand_id__content_autopilot_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Read the brand's content autopilot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentAutopilot"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:content","x-rankprompt-cost":{"request_units":1,"credits":0}},"patch":{"tags":["Content"],"summary":"Set up, change, pause or resume the content autopilot","description":"Send only what changes; the first change creates the autopilot. Requires the brand owner on Starter or with an active API subscription, except `{\"enabled\": false}` alone, which turns the autopilot off on any plan. A policy other than `draft_only` needs a destination: the `target_id` of a connection from `GET /v1/brands/{brand_id}/publish-targets` (`target_type` defaults to `cms_connection`), or `target_type: hosted_site` alone for the brand's hosted blog. Each article costs the brand owner the content credits `credits_per_article` reports, taken when the run starts. A month whose `monthly_cap` articles are written is not a pause: `next_run_at` is then the first slot of the next month, and a higher `monthly_cap` brings it back into this one. The autopilot pauses itself when the owner runs out of credits, when it finds no topic left, when the destination goes away or after three articles in a row failed to write or to publish; `resume: true` starts it again once that is fixed. A `plan` pause (the owner's plan no longer includes the autopilot) has no resume: it lifts on its own within the hour once the plan includes it again, and `resume: true` on it answers 400; a `blog_offline` pause (its hosted blog is offline for the owner's plan) lifts on its own once the blog is back, and answers 400 to `resume: true` too. Some fixes lift the pause in the same call: a saved destination lifts `target_missing`, and `blog_offline` when it is not that blog, and a new entry in `pinned_topics` lifts `no_topics`. A new `weekdays`, `publish_time` or `time_zone` moves an article already queued to its new slot; switching between `auto_publish` and `publish_after_review_window`, or a new `review_window_hours`, retimes the queued publishes on their slot; `draft_only` or another destination cancels the queued publishes and keeps those articles as drafts.","operationId":"update_content_autopilot_v1_brands__brand_id__content_autopilot_patch","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentAutopilotUpdate"}}}},"responses":{"200":{"description":"Set up, change, pause or resume the content autopilot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentAutopilot"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:content","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/content-autopilot/skipped-slots":{"post":{"tags":["Content"],"summary":"Skip one coming autopilot slot","description":"Leave one coming slot without an article: the autopilot writes nothing for it and charges nothing, and the slot does not count against `monthly_cap`. `slot_at` is a slot `GET /v1/brands/{brand_id}/content-calendar` lists with `source: autopilot`, at most three months ahead. A slot whose article the autopilot already started answers 409: delete or move that article instead. Any plan.","operationId":"create_content_autopilot_skipped_slot_v1_brands__brand_id__content_autopilot_skipped_slots_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutopilotSlotSkipCreate"}}}},"responses":{"200":{"description":"Skip one coming autopilot slot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutopilotSlotSkip"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:content","x-rankprompt-cost":{"request_units":2,"credits":0}},"delete":{"tags":["Content"],"summary":"Give a skipped autopilot slot back","description":"The autopilot writes the slot's article again, while the slot is still ahead. 404 when it was not skipped.","operationId":"delete_content_autopilot_skipped_slot_v1_brands__brand_id__content_autopilot_skipped_slots_delete","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"slot_at","in":"query","required":true,"schema":{"type":"string","format":"date-time","description":"The skipped slot, with its time zone.","title":"Slot At"},"description":"The skipped slot, with its time zone."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"204":{"description":"Give a skipped autopilot slot back","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:content","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/website-autopilot":{"get":{"tags":["Content"],"summary":"Read Website autopilot","description":"Website autopilot scans the brand's site each week on `scan_weekday` (in the owner's time zone), checks every page it reads and proposes changes to existing pages and new pages to create. This reads where it stands for the owner: `enabled` and the next scan, `scan` (the newest, `queued` or `running` while it reads the site), `decisions` (pages whose changes wait on the owner's review, with their undecided changes and questions), `stopped` (pages that cannot take their next step without the owner, each with the `step` it stopped at and the `reason`), `writing`, `live` (pages whose change or creation is on the site) and the cities with no page yet. `stopped` and `live` are offset paginated with their own `limit` and `offset`. Any plan; a client seat is refused.","operationId":"get_website_autopilot_v1_brands__brand_id__website_autopilot_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"stopped_limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Stopped pages per call (1-100, default 20).","default":20,"title":"Stopped Limit"},"description":"Stopped pages per call (1-100, default 20)."},{"name":"stopped_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Stopped pages to skip.","default":0,"title":"Stopped Offset"},"description":"Stopped pages to skip."},{"name":"live_limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Live pages per call (1-100, default 20).","default":20,"title":"Live Limit"},"description":"Live pages per call (1-100, default 20)."},{"name":"live_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Live pages to skip.","default":0,"title":"Live Offset"},"description":"Live pages to skip."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Read Website autopilot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebsiteAutopilot"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:seo","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/content-briefs/{brief_id}/interlinks":{"get":{"tags":["Content"],"summary":"List the posts that could link to an article","description":"Once an article goes live, the related posts on the same site are found (the sitemap, Search Console and the brand's other live articles), and one sentence is written per post that links to the article. Each proposal is `proposed` until someone applies or dismisses it, `applied` once the public page shows the link, or `task` when the site cannot be edited from here (Ghost, Shopify, Webflow, Wix, a webhook or a repository) or its public page does not show the edit, in which case a task with the sentence to paste was opened. Empty until the article is live. Requires the editor role on the brand, since the proposals are edits to its site.","operationId":"list_content_interlinks_v1_brands__brand_id__content_briefs__brief_id__interlinks_get","parameters":[{"name":"brief_id","in":"path","required":true,"schema":{"type":"string","title":"Brief Id"}},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned the posts that could link to an article","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentInterlinkList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:content","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/content-briefs/{brief_id}/interlinks/{interlink_id}/applications":{"post":{"tags":["Content"],"summary":"Add the link to the post","description":"Adds the sentence to the post on its site, as a paragraph after the one it relates to, reads the post back, then loads its public page to confirm visitors see the link. A post that already links to the article is not written again. On a site that cannot be edited from here, or whose public page does not show the link (a page builder or a cache drawing its own copy), the proposal becomes `task`. `409 conflict` while another link is being added to the same post; `503 service_unavailable` when the site does not answer, to retry later.","operationId":"apply_content_interlink_v1_brands__brand_id__content_briefs__brief_id__interlinks__interlink_id__applications_post","parameters":[{"name":"brief_id","in":"path","required":true,"schema":{"type":"string","title":"Brief Id"}},{"name":"interlink_id","in":"path","required":true,"schema":{"type":"string","title":"Interlink Id"}},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"201":{"description":"Add the link to the post","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentInterlink"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:content","x-rankprompt-cost":{"request_units":3,"credits":0}}},"/v1/brands/{brand_id}/content-briefs/{brief_id}/interlinks/{interlink_id}/dismissals":{"post":{"tags":["Content"],"summary":"Leave the post as it is","description":"Marks the proposal `dismissed`; one that had become a task closes that task too. `409 conflict` when the link is already on the site.","operationId":"dismiss_content_interlink_v1_brands__brand_id__content_briefs__brief_id__interlinks__interlink_id__dismissals_post","parameters":[{"name":"brief_id","in":"path","required":true,"schema":{"type":"string","title":"Brief Id"}},{"name":"interlink_id","in":"path","required":true,"schema":{"type":"string","title":"Interlink Id"}},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"201":{"description":"Leave the post as it is","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentInterlink"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:content","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/content-briefs":{"get":{"tags":["Content"],"summary":"List content briefs","description":"List a brand's content briefs, newest first. Each item omits the generated assets and the heavy `outline_json` / `research_output` fields; fetch a single brief by id to get those. Filter by `status`, exact `content_type`, and a free-text `search` on the title. Page by passing the response's `next_cursor` back as `cursor` until `has_more` is false.","operationId":"list_content_briefs_v1_brands__brand_id__content_briefs_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"enum":["draft","processing","needs_review","published","failed"],"type":"string"},{"type":"null"}],"description":"Restrict to a single brief `status`.","title":"Status"},"description":"Restrict to a single brief `status`."},{"name":"content_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"description":"Restrict to an exact `content_type` match.","title":"Content Type"},"description":"Restrict to an exact `content_type` match."},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Free-text search across brief titles.","title":"Search"},"description":"Free-text search across brief titles."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Page size (default 20, max 100).","default":20,"title":"Limit"},"description":"Page size (default 20, max 100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Continuation token from a previous response's `next_cursor`.","title":"Cursor"},"description":"Continuation token from a previous response's `next_cursor`."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned content briefs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentBriefList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:content","x-rankprompt-cost":{"request_units":2,"credits":0}},"post":{"tags":["Content"],"summary":"Create a content brief","description":"Create a content brief and generate its content inline, returning the finished article.\n\nThe AI pipeline runs synchronously and routinely takes minutes, so allow a long timeout, and prefer `POST /v1/brands/{brand_id}/content-briefs/generations` for anything unattended, which queues the same work and hands you a job to poll. A client that gives up on this request does not stop the pipeline: it keeps running and still charges.\n\nProvide a `topic` or at least one `target_keywords` entry. Costs credits, charged to the brand's owner.","operationId":"create_content_brief_v1_brands__brand_id__content_briefs_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentBriefCreate"}}}},"responses":{"201":{"description":"Created a content brief","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentBrief"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"402":{"description":"Not enough credits to complete this operation","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"insufficient_credits","message":"Not enough credits to complete this operation"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:content","x-rankprompt-cost":{"request_units":8,"credits":10},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}}},"/v1/brands/{brand_id}/content-briefs/citation-uplift":{"get":{"tags":["Content"],"summary":"Did the articles move the citations","description":"For each published article: how many prompts cited its URL in the reports before it went live, and how many since, plus which of the report prompts it was written to answer have come back. This is the only way to tell whether an article worked.\n\nPass up to 50 `brief_ids`, comma separated. Ids the brand does not own are left out. `reports_after: 0` means no report has run since it was published, so there is nothing to judge yet: run one, or wait for the schedule.","operationId":"get_citation_uplift_v1_brands__brand_id__content_briefs_citation_uplift_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"brief_ids","in":"query","required":true,"schema":{"type":"string","maxLength":4000,"description":"Comma-separated content brief ids, up to 50.","title":"Brief Ids"},"description":"Comma-separated content brief ids, up to 50."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Did the articles move the citations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CitationUpliftList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:content","x-rankprompt-cost":{"request_units":3,"credits":0}}},"/v1/brands/{brand_id}/content-briefs/ai-traffic":{"get":{"tags":["Content"],"summary":"AI visits per article","description":"For each published article: the GA4 sessions that AI assistants (ChatGPT, Perplexity, Gemini, Claude and others) referred to its page, in total and per assistant, with their key events. Read from the brand's GA4 property by landing page; Search Console never stands in, since it does not say a visit came from an assistant. `connected: false` means no GA4 property is linked; `reconnect: true` means the Google grant expired.\n\nPass up to 50 `brief_ids`, comma separated. Ids the brand does not own are left out. The window is the last 28 days in the property's time zone unless `start_date` and `end_date` say otherwise. Also needs the `read:analytics` scope. Free; kept 12 hours.","operationId":"get_article_ai_traffic_v1_brands__brand_id__content_briefs_ai_traffic_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"brief_ids","in":"query","required":true,"schema":{"type":"string","maxLength":4000,"description":"Comma-separated content brief ids, up to 50.","title":"Brief Ids"},"description":"Comma-separated content brief ids, up to 50."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}],"description":"YYYY-MM-DD; defaults to 28 days before end_date.","title":"Start Date"},"description":"YYYY-MM-DD; defaults to 28 days before end_date."},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}],"description":"YYYY-MM-DD; defaults to today.","title":"End Date"},"description":"YYYY-MM-DD; defaults to today."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"AI visits per article","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArticleAiTrafficList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:content","x-rankprompt-cost":{"request_units":3,"credits":0}}},"/v1/brands/{brand_id}/content-briefs/{brief_id}":{"get":{"tags":["Content"],"summary":"Retrieve a content brief","description":"Fetch a single content brief by id, including its generated assets (article HTML, images, meta), the structured `outline_json`, and the `research_output`. Cross-brand requests return `404 not_found`.","operationId":"get_content_brief_v1_brands__brand_id__content_briefs__brief_id__get","parameters":[{"name":"brief_id","in":"path","required":true,"schema":{"type":"string","description":"Content brief id (UUID).","title":"Brief Id"},"description":"Content brief id (UUID)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned a content brief","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentBrief"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:content","x-rankprompt-cost":{"request_units":3,"credits":0}},"patch":{"tags":["Content"],"summary":"Date a content brief on the calendar","description":"Set the brief's `planned_publish_at`, the day it sits on in the content calendar, or send `null` to take the date away (the article then waits undated, and its board task goes back to the backlog unless it is approved, done or dismissed). Nothing publishes from it.\n\n409 with `reason` `brief_generating` while the article is being written, `brief_published` once it is live, `brief_changed` when it started being written or went live during the request, and `publish_scheduled` when a publish is queued: move that one with `PATCH /v1/brands/{brand_id}/content-briefs/{brief_id}/publish-schedules/{schedule_id}`.","operationId":"update_content_brief_v1_brands__brand_id__content_briefs__brief_id__patch","parameters":[{"name":"brief_id","in":"path","required":true,"schema":{"type":"string","description":"Content brief id (UUID).","title":"Brief Id"},"description":"Content brief id (UUID)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentBriefUpdate"}}}},"responses":{"200":{"description":"Date a content brief on the calendar","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentBrief"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:content","x-rankprompt-cost":{"request_units":1,"credits":0}},"delete":{"tags":["Content"],"summary":"Delete a content brief","description":"Permanently delete a content brief, its published CMS posts, and its stored assets. Requires OWNER access on the brand. A brief that is still `processing` cannot be deleted.","operationId":"delete_content_brief_v1_brands__brand_id__content_briefs__brief_id__delete","parameters":[{"name":"brief_id","in":"path","required":true,"schema":{"type":"string","description":"Content brief id (UUID).","title":"Brief Id"},"description":"Content brief id (UUID)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"204":{"description":"Content brief deleted.","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:content","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/content-briefs/generations":{"post":{"tags":["Content"],"summary":"Generate an article asynchronously","description":"Create a content brief and run the AI pipeline in the background. Returns immediately with a `brief_id` and a `job_id`.\n\nPrefer this over `POST /v1/brands/{brand_id}/content-briefs` for anything unattended. Generation chains research, outline, writing and images and routinely runs for minutes. The synchronous endpoint holds the connection open for all of it and will time out on a slow article while the pipeline keeps running and is still charged.\n\nWorkflow:\n1. `POST /v1/brands/{brand_id}/content-briefs/generations`: returns `{ brief_id, job_id }`.\n2. `GET /v1/jobs/{job_id}`: poll until `status` is `completed`. `step` reports the pipeline phase (`research`, `outline`, `writer`, `editor`, `images`).\n3. `GET /v1/brands/{brand_id}/content-briefs/{brief_id}`: read the finished article.\n4. `POST /v1/brands/{brand_id}/content-briefs/{brief_id}/publish`: push it to a connected site.\n\nPricing: the same credits as the synchronous endpoint, charged to the brand's owner and debited when the job starts. The owner's balance is checked before the job is queued, so an underfunded owner means `402` here rather than a job that fails later. A failed generation is refunded automatically.\n\nRate limited more tightly than most endpoints; the exact limit is published as `x-rankprompt-rate-limit` on this operation.","operationId":"generate_content_brief_v1_brands__brand_id__content_briefs_generations_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentBriefCreate"}}}},"responses":{"202":{"description":"Content generation job dispatched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentBriefDispatched"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"402":{"description":"Not enough credits to complete this operation","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"insufficient_credits","message":"Not enough credits to complete this operation"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:content","x-rankprompt-cost":{"request_units":8,"credits":10},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}}},"/v1/brands/{brand_id}/content-briefs/{brief_id}/publish":{"post":{"tags":["Content"],"summary":"Publish a content brief","description":"Publish a finished brief and return it with its updated status.\n\nSet `target_type` to pick where it goes:\n- `cms_connection`: push the article to a connected site (WordPress, Ghost, Shopify, Webflow, Wix, a webhook or a GitHub repository). Pass the connection id from `GET /v1/brands/{brand_id}/cms-connections` as `target_id`. Publishing the same brief to the same connection again **updates the post in place** rather than creating a duplicate. A GitHub repository gets a pull request instead: the publication answers `draft` with its `review_url` and goes live when the pull request merges (a repository set to commit directly takes a live send straight onto its branch and answers `published` with no `review_url`); a draft send answers `draft` with its draft pull request as `review_url`, and is refused (400) on a post already live there; scheduled, it opens nothing on GitHub until its time, so the repository holds nothing while it waits.\n- `hosted_site`: publish to the brand's RankPrompt-hosted blog, which must already be active.\n- `external`: record an `external_url` you published yourself, pushing nothing anywhere.\n\nUse `publish_status: draft` to land the post as a CMS draft. `scheduled_for` queues the publish instead: the post waits on the site as a draft (the hosted blog keeps it in RankPrompt) and our queue makes it live at that time, retrying a site that does not answer. A draft cannot be scheduled: `publish_status: draft` with `scheduled_for` is a 400. A scheduled brief stays in `needs_review` until it actually goes live.\n\nPublishing approves any open review on the article.","operationId":"publish_content_brief_v1_brands__brand_id__content_briefs__brief_id__publish_post","parameters":[{"name":"brief_id","in":"path","required":true,"schema":{"type":"string","description":"Content brief id (UUID).","title":"Brief Id"},"description":"Content brief id (UUID)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentBriefPublish"}}}},"responses":{"200":{"description":"Publish a content brief","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentBrief"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:content","x-rankprompt-cost":{"request_units":3,"credits":0}}},"/v1/brands/{brand_id}/content-briefs/{brief_id}/publish-schedules/{schedule_id}":{"delete":{"tags":["Content"],"summary":"Cancel a scheduled publish","description":"Cancel a publish queued with `scheduled_for`, by the `schedule_id` of the brief's `scheduled`, `held` or `missed` publication. The draft already waiting on the site stays there as a draft, and the publication goes back to what the site holds. Cancelling one already cancelled succeeds and does nothing.\n\n409 when it can no longer be cancelled: the article is going live on that site right now (try again in a minute), it already went live, or it stopped after its retries.","operationId":"cancel_content_brief_publish_schedule_v1_brands__brand_id__content_briefs__brief_id__publish_schedules__schedule_id__delete","parameters":[{"name":"brief_id","in":"path","required":true,"schema":{"type":"string","description":"Content brief id (UUID).","title":"Brief Id"},"description":"Content brief id (UUID)."},{"name":"schedule_id","in":"path","required":true,"schema":{"type":"string","description":"The publication's `schedule_id` (UUID).","title":"Schedule Id"},"description":"The publication's `schedule_id` (UUID)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"204":{"description":"Scheduled publish cancelled.","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:content","x-rankprompt-cost":{"request_units":1,"credits":0}},"patch":{"tags":["Content"],"summary":"Move a scheduled publish","description":"Move a publish queued with `scheduled_for` to a new `run_at`, by the `schedule_id` of the brief's `scheduled`, `held` or `missed` publication, and get the brief back. Nothing is sent to the site again: the draft waiting there goes live at the new time, and the old time does nothing. A `held` one keeps waiting for the plan with its new time; a `missed` one is rescheduled and goes back to `scheduled`. `run_at` must be in the future.\n\n409 when it is no longer waiting in the queue (it went live, stopped after its retries, or was cancelled) or the article is going live on that site right now.","operationId":"move_content_brief_publish_schedule_v1_brands__brand_id__content_briefs__brief_id__publish_schedules__schedule_id__patch","parameters":[{"name":"brief_id","in":"path","required":true,"schema":{"type":"string","description":"Content brief id (UUID).","title":"Brief Id"},"description":"Content brief id (UUID)."},{"name":"schedule_id","in":"path","required":true,"schema":{"type":"string","description":"The publication's `schedule_id` (UUID).","title":"Schedule Id"},"description":"The publication's `schedule_id` (UUID)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublishScheduleMove"}}}},"responses":{"200":{"description":"Move a scheduled publish","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentBrief"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:content","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/content-briefs/manual":{"post":{"tags":["Content"],"summary":"Create a content brief from your own article","description":"Hand over an article you wrote yourself. Nothing is generated and **no credits are charged**: this is the endpoint to use when the writing happened somewhere else and RankPrompt is only hosting, reviewing and publishing it.\n\nThe brief lands in `needs_review` with the article attached, so everything downstream works the same as a generated one: edit it, share it for review with `PUT /v1/brands/{brand_id}/content-briefs/{brief_id}/review/share`, then publish it.\n\nUse `POST /v1/brands/{brand_id}/content-briefs` instead when you want RankPrompt to research and write the article for you; that one runs the AI pipeline and costs credits.","operationId":"create_manual_content_brief_v1_brands__brand_id__content_briefs_manual_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentBriefManualCreate"}}}},"responses":{"201":{"description":"Created a content brief from your own article","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentBrief"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:content","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/content-briefs/{brief_id}/review/share":{"put":{"tags":["Content"],"summary":"Share an article for review","description":"Create the article's review link, or refresh an existing one. The link opens a read-only view of the article where the recipient can leave comments and approve or request changes, no account, no login. Sharing moves the brief into the review stage.\n\nCalling this again on an already-shared article refreshes the same link and restarts its expiry rather than issuing a second one, so the URL you already sent keeps working. Send the returned `url` as-is.\n\nRequires the brand owner to be on Agency Plus.","operationId":"share_article_for_review_v1_brands__brand_id__content_briefs__brief_id__review_share_put","parameters":[{"name":"brief_id","in":"path","required":true,"schema":{"type":"string","description":"Content brief id (UUID).","title":"Brief Id"},"description":"Content brief id (UUID)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ReviewShareCreate"},{"type":"null"}],"title":"Body"}}}},"responses":{"200":{"description":"Share an article for review","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewShare"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:content","x-rankprompt-cost":{"request_units":2,"credits":0}},"delete":{"tags":["Content"],"summary":"Revoke an article's review link","description":"Kill the share link. The URL stops working immediately for anyone holding it, and the comments already left are kept. Revoking an article that was never shared succeeds and does nothing.\n\nOpen to every plan, so a link shared before a downgrade can still be taken down.","operationId":"revoke_article_review_share_v1_brands__brand_id__content_briefs__brief_id__review_share_delete","parameters":[{"name":"brief_id","in":"path","required":true,"schema":{"type":"string","description":"Content brief id (UUID).","title":"Brief Id"},"description":"Content brief id (UUID)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"204":{"description":"Review link revoked.","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:content","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/content-briefs/{brief_id}/review":{"get":{"tags":["Content"],"summary":"Retrieve an article's review","description":"The review state of an article and every comment on it, oldest first. Poll this after sharing to pick up client feedback: `status` tells you whether they approved or asked for changes, and each comment carries `anchor_quote` when it points at a specific passage.\n\nAn article that has never been shared is a valid empty state, not an error: `is_shared` is false, `status` is `pending` and `comments` is empty.","operationId":"get_article_review_v1_brands__brand_id__content_briefs__brief_id__review_get","parameters":[{"name":"brief_id","in":"path","required":true,"schema":{"type":"string","description":"Content brief id (UUID).","title":"Brief Id"},"description":"Content brief id (UUID)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned an article's review","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Review"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:content","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/content-briefs/{brief_id}/review/comments/{comment_id}":{"patch":{"tags":["Content"],"summary":"Resolve a review comment","description":"Mark a comment resolved once you have acted on it, or reopen it with `resolved: false`. Resolving is bookkeeping only: it does not notify the client and does not change the review's status.\n\nRequires the brand owner to be on Agency Plus.","operationId":"resolve_article_review_comment_v1_brands__brand_id__content_briefs__brief_id__review_comments__comment_id__patch","parameters":[{"name":"brief_id","in":"path","required":true,"schema":{"type":"string","description":"Content brief id (UUID).","title":"Brief Id"},"description":"Content brief id (UUID)."},{"name":"comment_id","in":"path","required":true,"schema":{"type":"string","description":"Review comment id (UUID).","title":"Comment Id"},"description":"Review comment id (UUID)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ReviewCommentUpdate"},{"type":"null"}],"title":"Body"}}}},"responses":{"200":{"description":"Resolve a review comment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewComment"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:content","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/content-briefs/{brief_id}/assets":{"patch":{"tags":["Content"],"summary":"Edit a generated article","description":"Rewrite the article's body, its metadata, or both, and get the brief back. `article_html` replaces the whole body and is sanitised; `meta` is merged over what the article already has, and `meta.title` becomes the brief's title, which is what publishes. Send `expected_updated_at` (the article asset's `updated_at`) to refuse the edit with 409 when the article changed since you read it.\n\nEditing an article that a client asked changes on opens a fresh review round on the same share link. Publishing again after an edit updates the live post in place.","operationId":"update_content_brief_assets_v1_brands__brand_id__content_briefs__brief_id__assets_patch","parameters":[{"name":"brief_id","in":"path","required":true,"schema":{"type":"string","description":"Content brief id (UUID).","title":"Brief Id"},"description":"Content brief id (UUID)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentAssetsUpdate"}}}},"responses":{"200":{"description":"Edit a generated article","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentBrief"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:content","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/content-briefs/{brief_id}/generations":{"post":{"tags":["Content"],"summary":"Write the article again","description":"Queue the generation pipeline over an existing brief, replacing its article. Costs what the first write cost, minus the outline when a usable one is already paid for, and needs Starter; the brand owner's balance is checked before it is queued. Poll the returned `job_id`.\n\nUse it when the brief's topic, keywords or context changed, or when the first article came out wrong. To keep the text and only fix a passage, edit it with `PATCH .../assets` instead: that costs nothing.","operationId":"regenerate_content_brief_v1_brands__brand_id__content_briefs__brief_id__generations_post","parameters":[{"name":"brief_id","in":"path","required":true,"schema":{"type":"string","description":"Content brief id (UUID).","title":"Brief Id"},"description":"Content brief id (UUID)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"current_defaults","in":"query","required":false,"schema":{"type":"boolean","description":"Write with the brand's content preferences of today. By default a rewrite keeps the brand values the last run used (`generation_settings`), so changing the brand's tone does not change it.","default":false,"title":"Current Defaults"},"description":"Write with the brand's content preferences of today. By default a rewrite keeps the brand values the last run used (`generation_settings`), so changing the brand's tone does not change it."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"202":{"description":"Write the article again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentBriefDispatched"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"402":{"description":"Not enough credits to complete this operation","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"insufficient_credits","message":"Not enough credits to complete this operation"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:content","x-rankprompt-cost":{"request_units":5,"credits":10},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}}},"/v1/brands/{brand_id}/content-briefs/{brief_id}/review/comments":{"post":{"tags":["Content"],"summary":"Reply on an article's review","description":"Answer the client on the review thread they see through the share link, and get the whole review back. Reply to one of their comments with `parent_comment_id`, and point at the passage with `anchor_quote`. Needs Agency Plus, like resolving a comment.","operationId":"create_review_comment_v1_brands__brand_id__content_briefs__brief_id__review_comments_post","parameters":[{"name":"brief_id","in":"path","required":true,"schema":{"type":"string","description":"Content brief id (UUID).","title":"Brief Id"},"description":"Content brief id (UUID)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewCommentCreate"}}}},"responses":{"201":{"description":"Reply on an article's review","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Review"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:content","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/content-plans":{"post":{"tags":["Content"],"summary":"Generate a batch of articles","description":"Queue up to 30 articles in one call: the balance is checked once for the whole plan, then each article runs on the single-article contract, with its own credit reserved and refunded if it fails. 10 credits each, 9 each when the plan holds 5 or more, 8 each from 20; Starter.\n\nPass your own `batch_id` so a retry cannot queue the same plan twice. Follow it with `GET /v1/brands/{brand_id}/content-plans/{batch_id}`. Build the items from `GET /v1/brands/{brand_id}/content-opportunities`: each row carries the topic, the keywords and the context to pass straight in, or pass a keyword cluster's `cluster_id` to plan its pillar and supports.","operationId":"create_content_plan_v1_brands__brand_id__content_plans_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentPlanCreate"}}}},"responses":{"202":{"description":"Generate a batch of articles","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentPlan"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"402":{"description":"Not enough credits to complete this operation","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"insufficient_credits","message":"Not enough credits to complete this operation"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:content","x-rankprompt-cost":{"request_units":10,"credits":0},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}}},"/v1/brands/{brand_id}/content-plans/{batch_id}":{"get":{"tags":["Content"],"summary":"Follow a batch of articles","description":"Where each article of a plan has got to, and the totals. Poll it instead of polling every job: `done` turns true when nothing is left running. `opportunity_id` comes back on the call that queued the plan, not here: keep it on your side if you need to reconcile.","operationId":"get_content_plan_v1_brands__brand_id__content_plans__batch_id__get","parameters":[{"name":"batch_id","in":"path","required":true,"schema":{"type":"string","description":"The plan's batch id.","title":"Batch Id"},"description":"The plan's batch id."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Follow a batch of articles","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentPlan"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:content","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/content-optimizations":{"post":{"tags":["Content"],"summary":"Optimize an existing page","description":"Improve a page the brand already publishes instead of writing a new one. The page is read as it is live, checked against what Google ranks for its keyword (subtopics the top results cover, People also ask, length) and against the article quality checks, and fixed at the `optimize_level` you pick. Only pages on the brand's own website can be optimized (`400 validation_error` otherwise), and a page that cannot be read fails the job before anything is charged.\n\nReturns `{ brief_id, job_id }` like `content-briefs/generations`: poll `GET /v1/jobs/{job_id}`, then read the brief. `quality_report.enforcement.optimize` holds the issues found, the sections changed, added or refused, and `score_before` and `score_after`. Publishing it to a connected site that holds the page updates that post in place.\n\nPricing: the credits of one article, charged to the brand's owner, refunded if the job fails. Starter.","operationId":"create_content_optimization_v1_brands__brand_id__content_optimizations_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentOptimizationCreate"}}}},"responses":{"202":{"description":"Optimization job dispatched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentBriefDispatched"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"402":{"description":"Not enough credits to complete this operation","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"insufficient_credits","message":"Not enough credits to complete this operation"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:content","x-rankprompt-cost":{"request_units":8,"credits":10},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}}},"/v1/brands/{brand_id}/cms-connections":{"get":{"tags":["Content"],"summary":"List CMS connections","description":"The CMS sites this brand can publish to. Use a connection's `id` as `target_id` when calling `POST /v1/brands/{brand_id}/content-briefs/{brief_id}/publish` with `target_type: cms_connection`.\n\nStored credentials are never returned, and a `webhook` connection's `site_url` is only its host unless you own the brand. `has_credentials` tells you whether a secret is on file, and `status` tells you whether it last worked. A brand holds at most one connection per provider, so this list is bounded and not paginated.","operationId":"list_cms_connections_v1_brands__brand_id__cms_connections_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned CMS connections","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CmsConnectionList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:cms","x-rankprompt-cost":{"request_units":1,"credits":0}},"post":{"tags":["Content"],"summary":"Connect a CMS","description":"Connect a WordPress site to this brand so its articles can be published there.\n\nThe credentials are verified against the live site before anything is stored: a site that is unreachable, or an application password WordPress rejects, returns `422 validation_error` and nothing is saved. Once stored, the application password is encrypted at rest and is never returned by this API.\n\nA brand holds one connection per provider, so posting again for the same provider replaces the stored credentials rather than adding a second connection. That is how you rotate an application password, and the connection keeps its id. Posting a different site replaces the connection with a new one under a new `id`: the old `target_id` no longer publishes, and articles already published stay recorded against the site they went to.\n\nRequires OWNER access on the brand.","operationId":"create_cms_connection_v1_brands__brand_id__cms_connections_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CmsConnectionCreate"}}}},"responses":{"201":{"description":"Connect a CMS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CmsConnection"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:cms","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/cms-connections/{connection_id}":{"get":{"tags":["Content"],"summary":"Retrieve a CMS connection","description":"Fetch one CMS connection by id, to resolve a `target_id` you are about to publish to. Credentials are never included, and a `webhook` connection's `site_url` is only its host unless you own the brand, since the rest of that URL is its secret. Cross-brand requests return `404 not_found`.","operationId":"get_cms_connection_v1_brands__brand_id__cms_connections__connection_id__get","parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","description":"CMS connection id (UUID).","title":"Connection Id"},"description":"CMS connection id (UUID)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned a CMS connection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CmsConnection"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:cms","x-rankprompt-cost":{"request_units":1,"credits":0}},"delete":{"tags":["Content"],"summary":"Delete a CMS connection","description":"Disconnect the CMS and delete its stored credentials. Posts already published to the site are left alone; this only severs our ability to publish or update them. Requires OWNER access on the brand.","operationId":"delete_cms_connection_v1_brands__brand_id__cms_connections__connection_id__delete","parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","description":"CMS connection id (UUID).","title":"Connection Id"},"description":"CMS connection id (UUID)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"204":{"description":"CMS connection deleted.","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:cms","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/cms-connections/{connection_id}/checks":{"post":{"tags":["Content"],"summary":"Check a CMS connection","description":"Re-verify the stored credentials against the live site without publishing anything, and record the outcome on the connection.\n\nApplication passwords get revoked in WordPress and sites move behind new firewalls, and nothing tells us until a publish fails. Run this across your connections on a schedule to find the broken ones before they cost you a publish window.\n\nA failed check is a normal `201` response with `ok: false` and a reason. It is a report, not an error. The connection's `status` becomes `connected` or `error` to match, and `last_synced_at` only advances when the check succeeds.\n\nRequires OWNER access on the brand.","operationId":"check_cms_connection_v1_brands__brand_id__cms_connections__connection_id__checks_post","parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","description":"CMS connection id (UUID).","title":"Connection Id"},"description":"CMS connection id (UUID)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"201":{"description":"Check performed; read `ok` for the outcome.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CmsConnectionCheck"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:cms","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/audits":{"get":{"tags":["Brand audits"],"summary":"List brand audits","description":"List a brand's audits, newest first. Cursor-paginated. Each item omits the large per-platform analysis fields (`web_search_results`, `knowledge_results`, reputation results); fetch a single audit by id to get those. Filter by `status`, exact `country`, and a free-text `search` (matches country / location / language).","operationId":"list_brand_audits_v1_brands__brand_id__audits_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"enum":["processing","completed","failed"],"type":"string"},{"type":"null"}],"description":"Restrict to a single audit `status`.","title":"Status"},"description":"Restrict to a single audit `status`."},{"name":"country","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Restrict to an exact `country` match.","title":"Country"},"description":"Restrict to an exact `country` match."},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Free-text search across `country`, `location`, and `language`.","title":"Search"},"description":"Free-text search across `country`, `location`, and `language`."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Page size (default 20, max 100).","default":20,"title":"Limit"},"description":"Page size (default 20, max 100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Continuation token from a previous response's `next_cursor`.","title":"Cursor"},"description":"Continuation token from a previous response's `next_cursor`."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned brand audits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandAuditList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:brand-audits","x-rankprompt-cost":{"request_units":2,"credits":0}},"post":{"tags":["Brand audits"],"summary":"Run a brand audit","description":"Run an AI-visibility brand audit for a market (`country` + `language`) and return the finished audit. The analysis runs inline and takes minutes, so set a long timeout. Costs credits, charged to the brand's owner.\n\nFor unattended clients use `POST /v1/brands/{brand_id}/audits/runs` instead, which returns an `audit_id` immediately. If this request times out the audit still runs and is still charged, and you have no id to retrieve it with.","operationId":"create_brand_audit_v1_brands__brand_id__audits_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandAuditCreate"}}}},"responses":{"201":{"description":"Run a brand audit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandAudit"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"402":{"description":"Not enough credits to complete this operation","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"insufficient_credits","message":"Not enough credits to complete this operation"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:brand-audits","x-rankprompt-cost":{"request_units":8,"credits":10},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}}},"/v1/brands/{brand_id}/audits/{audit_id}":{"get":{"tags":["Brand audits"],"summary":"Retrieve a brand audit","description":"Fetch a single brand audit by id, including the full per-platform analysis (`web_search_results`, `knowledge_results`, reputation results) and the per-page citation analysis. Cross-brand requests return `404 not_found`.","operationId":"get_brand_audit_v1_brands__brand_id__audits__audit_id__get","parameters":[{"name":"audit_id","in":"path","required":true,"schema":{"type":"string","description":"Brand audit id (UUID).","title":"Audit Id"},"description":"Brand audit id (UUID)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned a brand audit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandAudit"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:brand-audits","x-rankprompt-cost":{"request_units":3,"credits":0}}},"/v1/brands/{brand_id}/audits/runs":{"post":{"tags":["Brand audits"],"summary":"Run a brand audit asynchronously","description":"Queue an AI-visibility brand audit for a market (`country` + `language`) and return immediately with an `audit_id` and a `job_id`. Prefer this over `POST /v1/brands/{brand_id}/audits` for unattended clients: an audit queries several AI platforms and takes minutes.\n\n1. `POST /v1/brands/{brand_id}/audits/runs` returns `{ audit_id, job_id }`.\n2. `GET /v1/jobs/{job_id}`: poll until `status` is `completed`.\n3. `GET /v1/brands/{brand_id}/audits/{audit_id}`: read the finished audit.\n\nCosts the same credits as the synchronous endpoint, charged to the brand's owner. The owner's balance is checked up front, so an underfunded owner means `402` from this call rather than a job that fails later; a failed audit is refunded.","operationId":"dispatch_brand_audit_v1_brands__brand_id__audits_runs_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandAuditCreate"}}}},"responses":{"202":{"description":"Brand audit job dispatched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandAuditDispatched"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"402":{"description":"Not enough credits to complete this operation","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"insufficient_credits","message":"Not enough credits to complete this operation"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:brand-audits","x-rankprompt-cost":{"request_units":8,"credits":10},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}}},"/v1/brands/{brand_id}/audits/{audit_id}/recommendations":{"post":{"tags":["Brand audits"],"summary":"Generate audit recommendations","description":"Generate SEO/AEO recommendations for a completed audit and return the updated audit. Costs 3 credits flat, which include the analysis of up to 10 cited pages run first when none is analyzed yet. Pass `force_regenerate=true` to replace existing recommendations (charges again). The generation takes minutes: pass `async: true` to get `202` with a `job_id` at once, the credits held.","operationId":"generate_brand_audit_recommendations_v1_brands__brand_id__audits__audit_id__recommendations_post","parameters":[{"name":"audit_id","in":"path","required":true,"schema":{"type":"string","description":"Brand audit id (UUID).","title":"Audit Id"},"description":"Brand audit id (UUID)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandAuditRecommendations"}}}},"responses":{"200":{"description":"Generate audit recommendations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandAudit"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"202":{"description":"Queued (`async: true`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandAuditRecommendationsDispatched"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"402":{"description":"Not enough credits to complete this operation","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"insufficient_credits","message":"Not enough credits to complete this operation"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:brand-audits","x-rankprompt-cost":{"request_units":5,"credits":3},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}}},"/v1/brands/{brand_id}/audits/{audit_id}/citations":{"post":{"tags":["Brand audits"],"summary":"Analyze audit citations","description":"Queue a deep citation analysis of specific pages for a completed audit. Returns a `job_id` to poll on `GET /v1/jobs/{job_id}`. Costs one credit per three newly analyzed pages, rounded up; pages analyzed before and retries of failed ones are free, and a page that cannot be read is refunded.","operationId":"analyze_brand_audit_citations_v1_brands__brand_id__audits__audit_id__citations_post","parameters":[{"name":"audit_id","in":"path","required":true,"schema":{"type":"string","description":"Brand audit id (UUID).","title":"Audit Id"},"description":"Brand audit id (UUID)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandAuditCitationAnalysisRequest"}}}},"responses":{"202":{"description":"Analyze audit citations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandAuditCitationAnalysisDispatched"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"402":{"description":"Not enough credits to complete this operation","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"insufficient_credits","message":"Not enough credits to complete this operation"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:brand-audits","x-rankprompt-cost":{"request_units":3,"credits":1},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}}},"/v1/brands/{brand_id}/audits/{audit_id}/shares":{"get":{"tags":["Shares"],"summary":"List brand-audit shares","description":"List the caller's non-expired public share links for a brand audit (newest first).\n\nOnly shares created by the authenticated principal are returned: shares created by other teammates are not visible.","operationId":"list_brand_audit_shares_v1_brands__brand_id__audits__audit_id__shares_get","parameters":[{"name":"audit_id","in":"path","required":true,"schema":{"type":"string","description":"Brand audit id (UUID).","title":"Audit Id"},"description":"Brand audit id (UUID)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned brand-audit shares","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandAuditShareList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:brand-audits","x-rankprompt-cost":{"request_units":1,"credits":0}},"post":{"tags":["Shares"],"summary":"Create a brand-audit share","description":"Create a public share link to a read-only snapshot of a single brand audit (its analysis, recommendations and citation breakdown).\n\nIf the caller already has a share for this audit, the **same** token is returned (`is_existing=true`). Pass `rotate=true` to drop the existing share and mint a fresh token (use this when a previous link may have been leaked).\n\nDefaults: 30-day expiry, no rotation. The caller's account-level white-label branding is applied automatically.\n\nReturns `400 validation_error` once the audit already has 50 active shares.","operationId":"create_brand_audit_share_v1_brands__brand_id__audits__audit_id__shares_post","parameters":[{"name":"audit_id","in":"path","required":true,"schema":{"type":"string","description":"Brand audit id (UUID).","title":"Audit Id"},"description":"Brand audit id (UUID)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/BrandAuditShareCreate"},{"type":"null"}],"description":"Share config (optional; defaults to 30-day expiry, no rotation).","title":"Payload"}}}},"responses":{"201":{"description":"Created a brand-audit share","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandAuditShare"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:brand-audits","x-rankprompt-cost":{"request_units":3,"credits":0}},"delete":{"tags":["Shares"],"summary":"Revoke brand-audit shares","description":"Revoke every share link the caller owns for this brand audit. Idempotent: calling it again on an audit with no shares returns `204` no-op.\n\nCannot remove shares created by other teammates.","operationId":"delete_brand_audit_shares_v1_brands__brand_id__audits__audit_id__shares_delete","parameters":[{"name":"audit_id","in":"path","required":true,"schema":{"type":"string","description":"Brand audit id (UUID).","title":"Audit Id"},"description":"Brand audit id (UUID)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"204":{"description":"Revoke brand-audit shares","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:brand-audits","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/audits/{audit_id}/shares/{share_id}":{"patch":{"tags":["Shares"],"summary":"Extend a brand-audit share","description":"Reset a share's `expires_at` to `now + expiration_days` (1-365). Anchored to **now**: the new expiry is predictable regardless of any remaining time on the previous window.\n\nOnly the share's owner can extend it.","operationId":"update_brand_audit_share_v1_brands__brand_id__audits__audit_id__shares__share_id__patch","parameters":[{"name":"audit_id","in":"path","required":true,"schema":{"type":"string","description":"Brand audit id (UUID).","title":"Audit Id"},"description":"Brand audit id (UUID)."},{"name":"share_id","in":"path","required":true,"schema":{"type":"string","description":"Share id (UUID).","title":"Share Id"},"description":"Share id (UUID)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandAuditShareUpdate"}}}},"responses":{"200":{"description":"Extend a brand-audit share","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandAuditShare"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:brand-audits","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/seo-pages/candidates":{"get":{"tags":["SEO pages"],"summary":"List pages to track","description":"Read up to 5000 pages of the brand's sitemap and list the published ones that are not tracked SEO pages yet, to pick which to track with `POST /v1/brands/{brand_id}/seo-pages`; `count_is_partial` says the walk stopped before the end. `sitemap_url` reads a sitemap other than the one the site declares; it must be on the brand's own host, else `400`. A brand without a website answers `400`; a site without a readable sitemap lists nothing. Offset paginated over the sitemap's order: a walk is reused for 5 minutes, so paging does not read the site again. Rate limited like the endpoints that run a language model.","operationId":"list_seo_page_candidates_v1_brands__brand_id__seo_pages_candidates_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"sitemap_url","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A sitemap to read instead of the site's.","title":"Sitemap Url"},"description":"A sitemap to read instead of the site's."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Pages per call (1-500, default 50).","default":50,"title":"Limit"},"description":"Pages per call (1-500, default 50)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Pages to skip.","default":0,"title":"Offset"},"description":"Pages to skip."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned pages to track","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoPageCandidateList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:seo","x-rankprompt-cost":{"request_units":3,"credits":0},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}}},"/v1/brands/{brand_id}/seo-pages":{"get":{"tags":["SEO pages"],"summary":"List tracked pages","description":"List the pages you track for this brand, newest first. Each item includes the page's most recent completed audit (when one exists) and whether an audit is currently running. The list is bounded per brand, so it is not paginated.","operationId":"list_seo_pages_v1_brands__brand_id__seo_pages_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned tracked pages","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoPageList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:seo","x-rankprompt-cost":{"request_units":1,"credits":0}},"post":{"tags":["SEO pages"],"summary":"Track a page","description":"Start tracking a page so you can run Lighthouse audits and technical SEO checks on it. The URL must belong to a site you can audit (social and video platforms are rejected). Each brand can track a limited number of pages.","operationId":"create_seo_page_v1_brands__brand_id__seo_pages_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoPageCreate"}}}},"responses":{"201":{"description":"Track a page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoPage"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:seo","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/seo-pages/{page_id}":{"get":{"tags":["SEO pages"],"summary":"Retrieve a tracked page","description":"Fetch a single tracked page, including its most recent completed audit and whether an audit is currently running. Cross-brand requests return `404 not_found`.","operationId":"get_seo_page_v1_brands__brand_id__seo_pages__page_id__get","parameters":[{"name":"page_id","in":"path","required":true,"schema":{"type":"string","description":"Page id (UUID).","title":"Page Id"},"description":"Page id (UUID)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned a tracked page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoPage"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:seo","x-rankprompt-cost":{"request_units":1,"credits":0}},"patch":{"tags":["SEO pages"],"summary":"Update a tracked page","description":"Update a tracked page's label or device profile. Only the fields you send change.","operationId":"update_seo_page_v1_brands__brand_id__seo_pages__page_id__patch","parameters":[{"name":"page_id","in":"path","required":true,"schema":{"type":"string","description":"Page id (UUID).","title":"Page Id"},"description":"Page id (UUID)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoPageUpdate"}}}},"responses":{"200":{"description":"Updated a tracked page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoPage"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:seo","x-rankprompt-cost":{"request_units":1,"credits":0}},"delete":{"tags":["SEO pages"],"summary":"Stop tracking a page","description":"Stop tracking a page and delete its audits and technical checks. Fails while an audit is still running; wait for it to finish, then retry.","operationId":"delete_seo_page_v1_brands__brand_id__seo_pages__page_id__delete","parameters":[{"name":"page_id","in":"path","required":true,"schema":{"type":"string","description":"Page id (UUID).","title":"Page Id"},"description":"Page id (UUID)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"204":{"description":"Page deleted.","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:seo","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/seo-pages/{page_id}/audits":{"get":{"tags":["SEO pages"],"summary":"List page audits","description":"List a page's Lighthouse audits, newest first. Cursor-paginated. Each item omits the detailed per-check issues and real-user field data; fetch a single audit by id to get those.","operationId":"list_seo_audits_v1_brands__brand_id__seo_pages__page_id__audits_get","parameters":[{"name":"page_id","in":"path","required":true,"schema":{"type":"string","description":"Page id (UUID).","title":"Page Id"},"description":"Page id (UUID)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Page size (default 20, max 100).","default":20,"title":"Limit"},"description":"Page size (default 20, max 100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Continuation token from a previous response's `next_cursor`.","title":"Cursor"},"description":"Continuation token from a previous response's `next_cursor`."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned page audits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoAuditList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:seo","x-rankprompt-cost":{"request_units":1,"credits":0}},"post":{"tags":["SEO pages"],"summary":"Run a page audit","description":"Queue a new Lighthouse audit for the page. The audit runs in the background, so this returns immediately with an audit whose `status` is `processing`; poll `GET /v1/brands/{brand_id}/seo-pages/{page_id}/audits/{audit_id}` until it is `completed` or `failed`. Costs one credit, charged to the brand's owner.","operationId":"run_seo_audit_v1_brands__brand_id__seo_pages__page_id__audits_post","parameters":[{"name":"page_id","in":"path","required":true,"schema":{"type":"string","description":"Page id (UUID).","title":"Page Id"},"description":"Page id (UUID)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"202":{"description":"Run a page audit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoAudit"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"402":{"description":"Not enough credits to complete this operation","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"insufficient_credits","message":"Not enough credits to complete this operation"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:seo","x-rankprompt-cost":{"request_units":3,"credits":1},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}}},"/v1/brands/{brand_id}/seo-pages/{page_id}/audits/{audit_id}":{"get":{"tags":["SEO pages"],"summary":"Retrieve a page audit","description":"Fetch a single audit by id, including its Lighthouse category scores, Core Web Vitals, the detailed per-check issues, and real-user field data. Cross-brand requests return `404 not_found`.","operationId":"get_seo_audit_v1_brands__brand_id__seo_pages__page_id__audits__audit_id__get","parameters":[{"name":"page_id","in":"path","required":true,"schema":{"type":"string","description":"Page id (UUID).","title":"Page Id"},"description":"Page id (UUID)."},{"name":"audit_id","in":"path","required":true,"schema":{"type":"string","description":"Audit id (UUID).","title":"Audit Id"},"description":"Audit id (UUID)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned a page audit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoAudit"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:seo","x-rankprompt-cost":{"request_units":1,"credits":0}},"delete":{"tags":["SEO pages"],"summary":"Delete a page audit","description":"Delete an audit by id. Fails while the audit is still running.","operationId":"delete_seo_audit_v1_brands__brand_id__seo_pages__page_id__audits__audit_id__delete","parameters":[{"name":"page_id","in":"path","required":true,"schema":{"type":"string","description":"Page id (UUID).","title":"Page Id"},"description":"Page id (UUID)."},{"name":"audit_id","in":"path","required":true,"schema":{"type":"string","description":"Audit id (UUID).","title":"Audit Id"},"description":"Audit id (UUID)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"204":{"description":"Audit deleted.","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:seo","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/seo-pages/{page_id}/technical-checks":{"get":{"tags":["SEO pages"],"summary":"Retrieve the latest technical check","description":"Fetch the most recent technical SEO check for a page: an overall score plus per-category findings (robots.txt, sitemap, meta robots, canonical, Open Graph, Twitter card, schema.org, indexability, SSL, redirects, internal links, meta content, headings, hreflang, images, security headers, page weight). Returns `404 not_found` when no check has been run yet; run one with `POST`.","operationId":"get_seo_technical_check_v1_brands__brand_id__seo_pages__page_id__technical_checks_get","parameters":[{"name":"page_id","in":"path","required":true,"schema":{"type":"string","description":"Page id (UUID).","title":"Page Id"},"description":"Page id (UUID)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned the latest technical check","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoTechnicalCheck"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:seo","x-rankprompt-cost":{"request_units":1,"credits":0}},"post":{"tags":["SEO pages"],"summary":"Run a technical check","description":"Crawl the page and run a fresh technical SEO check, returning the completed result. The crawl runs inline and can take a moment. Only public pages on your own site can be checked.","operationId":"run_seo_technical_check_v1_brands__brand_id__seo_pages__page_id__technical_checks_post","parameters":[{"name":"page_id","in":"path","required":true,"schema":{"type":"string","description":"Page id (UUID).","title":"Page Id"},"description":"Page id (UUID)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"201":{"description":"Run a technical check","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoTechnicalCheck"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:seo","x-rankprompt-cost":{"request_units":3,"credits":0},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}}},"/v1/brands/{brand_id}/seo-pages/{page_id}/crux-history":{"get":{"tags":["SEO pages"],"summary":"Retrieve Core Web Vitals trend","description":"Fetch the weekly Core Web Vitals trend (75th percentile) for a page, sourced from real Chrome users. `available` is false and `history` is `null` when the page does not have enough real-user data to report a trend.","operationId":"get_seo_crux_history_v1_brands__brand_id__seo_pages__page_id__crux_history_get","parameters":[{"name":"page_id","in":"path","required":true,"schema":{"type":"string","description":"Page id (UUID).","title":"Page Id"},"description":"Page id (UUID)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned Core Web Vitals trend","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoCruxHistory"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:seo","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/schema-templates":{"get":{"tags":["SEO pages"],"summary":"Get schema.org templates","description":"Get ready-to-paste schema.org (JSON-LD) templates for the brand, such as Organization, Website, FAQ, and How-To, each with a short instruction on where to paste it. When the brand has linked Google Business Profile locations, each one gets a LocalBusiness template of its schema.org subtype.","operationId":"get_seo_schema_templates_v1_brands__brand_id__schema_templates_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned schema.org templates","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoSchemaTemplates"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:seo","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/ai-crawlers":{"get":{"tags":["SEO pages"],"summary":"Read AI crawler activity","description":"What AI crawlers (GPTBot, OAI-SearchBot, ChatGPT-User, ClaudeBot, PerplexityBot and the rest) fetched from the brand's site over the last `days` days: per crawler, its requests, how many came from its operator's published addresses (verified), how many hit a 4xx or 5xx, and how many pages it fetched. Read from the logs the brand's sources already sent (an uploaded access log, Cloudflare, a Vercel log drain or WordPress, set up in the app); it never fetches a log. `sources` lists them with their status, the hosts they read and when they last delivered, so an empty result tells no visits from no source. Every plan reads it; connecting a source needs Pro. Free.","operationId":"get_ai_crawler_activity_v1_brands__brand_id__ai_crawlers_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"days","in":"query","required":false,"schema":{"type":"integer","maximum":400,"minimum":1,"description":"Days back from today, today included (1 to 400).","default":30,"title":"Days"},"description":"Days back from today, today included (1 to 400)."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Read AI crawler activity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiCrawlerActivity"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:seo","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/seo/keywords":{"get":{"tags":["SEO keywords"],"summary":"List the keyword library","description":"A page of the brand's keyword library: saved keywords and the rank tracked ones, each with its search volume, difficulty and intent, its last, previous and best position, the brand page that ranked, its opportunity score and the article that targets it, plus totals over the rank tracked rows (top 3, top 10, improved, declined) and the plan's limits. Offset-paginated and filtered and sorted over the whole library: `filter` narrows to rank tracked, saved, recommended or starred keywords, `status` to the article's state, `ai_overview` to what Google's AI Overview does with the brand, `cluster_id` to the members of one keyword cluster.","operationId":"list_keywords_v1_brands__brand_id__seo_keywords_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Page size (1-100).","default":20,"title":"Limit"},"description":"Page size (1-100)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Keywords to skip.","default":0,"title":"Offset"},"description":"Keywords to skip."},{"name":"sort","in":"query","required":false,"schema":{"enum":["created","keyword","source","page","volume","ai","questions","kd","intent","market","position","best","checked","opportunity"],"type":"string","description":"Column the rows are ordered by.","default":"created","title":"Sort"},"description":"Column the rows are ordered by."},{"name":"order","in":"query","required":false,"schema":{"enum":["asc","desc"],"type":"string","description":"`asc` or `desc`.","default":"desc","title":"Order"},"description":"`asc` or `desc`."},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Only keywords containing this text.","title":"Search"},"description":"Only keywords containing this text."},{"name":"filter","in":"query","required":false,"schema":{"enum":["all","rank_tracked","saved","recommended","starred","planned","published","failed"],"type":"string","description":"`all`, `rank_tracked`, `saved` (no rank checks), `recommended` (high score, no article yet), `starred`, or an article state: `planned`, `published`, `failed`.","default":"all","title":"Filter"},"description":"`all`, `rank_tracked`, `saved` (no rank checks), `recommended` (high score, no article yet), `starred`, or an article state: `planned`, `published`, `failed`."},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"enum":["planned","generating","ready","published","failed","none"],"type":"string"},{"type":"null"}],"description":"Only keywords whose newest article is in this state; `none` for no article.","title":"Status"},"description":"Only keywords whose newest article is in this state; `none` for no article."},{"name":"ai_overview","in":"query","required":false,"schema":{"anyOf":[{"enum":["any","shows","cites","names","not_you"],"type":"string"},{"type":"null"}],"description":"`shows` (Google answers with an AI Overview), `cites` (it cites the brand's site), `names` (its text names the brand), `not_you` (shown, without the brand), or `any`.","title":"Ai Overview"},"description":"`shows` (Google answers with an AI Overview), `cites` (it cites the brand's site), `names` (its text names the brand), `not_you` (shown, without the brand), or `any`."},{"name":"cluster_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only the keywords of this cluster.","title":"Cluster Id"},"description":"Only the keywords of this cluster."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned the keyword library","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackedKeywordList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:seo","x-rankprompt-cost":{"request_units":1,"credits":0}},"post":{"tags":["SEO keywords"],"summary":"Track keywords","description":"Start tracking keywords in Google (duplicates are skipped) and buy their search volume, difficulty and intent where not cached. Queue positions with `POST .../seo/keywords/rank-checks`.\n\nCredits are charged per batch, only for what is actually bought, and reported in `credits_charged`: Google numbers 1 credit per batch of keywords, rank checks 1 per 10 keywords, research 1 per seed (free when cached for the day), a domain overview 1 per 5 domains bought, a keyword gap 1 for up to 5 competitors, one site's ranking keywords 1 (free while cached for the week). Every plan can use keywords; the plan caps how many are tracked and how many checks run a day, and a cap answers `402 insufficient_credits` with `details.reason: plan_limit`.","operationId":"add_keywords_v1_brands__brand_id__seo_keywords_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeywordsCreate"}}}},"responses":{"201":{"description":"Track keywords","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeywordsAdded"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"402":{"description":"Not enough credits to complete this operation","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"insufficient_credits","message":"Not enough credits to complete this operation"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:seo","x-rankprompt-cost":{"request_units":2,"credits":0},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}},"delete":{"tags":["SEO keywords"],"summary":"Stop tracking several keywords","description":"Stop tracking the keywords in `ids`, with their rank history. Up to 200 per call, since they travel in the query string. Answers 404 if none of them exist.","operationId":"delete_keywords_v1_brands__brand_id__seo_keywords_delete","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"ids","in":"query","required":true,"schema":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":200,"description":"Tracked keyword ids to drop, up to 200 per call.","title":"Ids"},"description":"Tracked keyword ids to drop, up to 200 per call."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"204":{"description":"Stop tracking several keywords","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:seo","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/seo/competitor-domains":{"post":{"tags":["SEO keywords"],"summary":"Add a competitor site","description":"Compare against a site the reports did not find: it joins the keyword gap and the Google comparison, before the report competitors. Nothing is bought until a refresh asks for it. Up to 20 per brand.","operationId":"add_competitor_domain_v1_brands__brand_id__seo_competitor_domains_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompetitorDomainCreate"}}}},"responses":{"201":{"description":"Add a competitor site","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompetitorDomain"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:seo","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/seo/competitor-domains/{domain}":{"delete":{"tags":["SEO keywords"],"summary":"Remove a competitor site","description":"Remove a competitor site added by hand. The ones the reports found stay.","operationId":"remove_competitor_domain_v1_brands__brand_id__seo_competitor_domains__domain__delete","parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string","description":"The registrable domain, like salesforce.com.","title":"Domain"},"description":"The registrable domain, like salesforce.com."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"204":{"description":"Remove a competitor site","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:seo","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/seo/domains/{domain}/ranking-keywords":{"get":{"tags":["SEO keywords"],"summary":"List a site's ranking keywords","description":"A page of the keywords the brand's own site or one of its competitors ranks for in Google's top 100, best positions first, each with volume, difficulty, intent and whether the brand already tracks it. Reads the weekly cache only and costs nothing; `cached` false means the site was never loaded.","operationId":"domain_ranking_keywords_v1_brands__brand_id__seo_domains__domain__ranking_keywords_get","parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string","description":"The registrable domain, like salesforce.com.","title":"Domain"},"description":"The registrable domain, like salesforce.com."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Page size (1-100).","default":20,"title":"Limit"},"description":"Page size (1-100)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Keywords to skip.","default":0,"title":"Offset"},"description":"Keywords to skip."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned a site's ranking keywords","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainRankingKeywords"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:seo","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/seo/domains/{domain}/ranking-keywords/refreshes":{"post":{"tags":["SEO keywords"],"summary":"Load a site's ranking keywords","description":"Buy the keywords the brand's own site or one of its competitors ranks for in Google's top 100 in the brand's market, and return the first page. 1 credit, refunded when the vendor fails or Google lists nothing; free while this week's list is cached (the cache is shared, so a site another brand loaded this week costs nothing). `?dry_run=true` prices it; `load_credits` on the GET says the same.","operationId":"refresh_domain_ranking_keywords_v1_brands__brand_id__seo_domains__domain__ranking_keywords_refreshes_post","parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string","description":"The registrable domain, like salesforce.com.","title":"Domain"},"description":"The registrable domain, like salesforce.com."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Page size (1-100).","default":20,"title":"Limit"},"description":"Page size (1-100)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Load a site's ranking keywords","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainRankingKeywords"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"402":{"description":"Not enough credits to complete this operation","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"insufficient_credits","message":"Not enough credits to complete this operation"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:seo","x-rankprompt-cost":{"request_units":3,"credits":0},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}}},"/v1/brands/{brand_id}/seo/serp-snapshots":{"post":{"tags":["SEO keywords"],"summary":"Read a keyword's Google page","description":"The Google page of any keyword in the brand's market now: the top ten with the brand's place in it, People also ask, related searches and the AI Overview with its sources and whether it cites or names the brand. Free when any check read the same page in the last 20 hours (`cached`), otherwise 1 credit, refunded when Google returns nothing. The keyword is saved to the library without rank checks. `?dry_run=true` prices it.","operationId":"view_serp_v1_brands__brand_id__seo_serp_snapshots_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SerpViewCreate"}}}},"responses":{"200":{"description":"Read a keyword's Google page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SerpView"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"402":{"description":"Not enough credits to complete this operation","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"insufficient_credits","message":"Not enough credits to complete this operation"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:seo","x-rankprompt-cost":{"request_units":2,"credits":0},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}}},"/v1/brands/{brand_id}/seo/rank-schedule":{"get":{"tags":["SEO keywords"],"summary":"Get the rank check schedule","description":"How often the rank tracked keywords are checked on their own, when next, and what a week costs.","operationId":"get_rank_schedule_v1_brands__brand_id__seo_rank_schedule_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned the rank check schedule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RankSchedule"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:seo","x-rankprompt-cost":{"request_units":1,"credits":0}},"put":{"tags":["SEO keywords"],"summary":"Set the rank check schedule","description":"Check the rank tracked keywords `weekly`, `twice_weekly` or never (`off`). Each run is the same check as `POST /keywords/rank-checks`: 1 credit per 10 keywords, keywords checked in the last 20 hours skipped, within the plan's daily rank checks, charged to the brand owner when it runs. The response carries `weekly_credits`. A run that finds too few credits pauses the schedule (`paused_reason`); saving it again resumes it. The first run starts within the hour.","operationId":"save_rank_schedule_v1_brands__brand_id__seo_rank_schedule_put","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RankScheduleUpdate"}}}},"responses":{"200":{"description":"Set the rank check schedule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RankSchedule"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:seo","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/seo/keyword-clusters":{"get":{"tags":["SEO keywords"],"summary":"List keyword clusters","description":"A page of the brand's keyword clusters with their members' volume, average position, AI Overviews, report prompts and articles. List a cluster's keywords with `GET /keywords?cluster_id=`.\n\nClusters group the keyword library into topics: keywords whose Google top 10 shares 3 or more pages with the most searched one (the pillar), and, for keywords without recent Google results, the ones sharing its wording. They are rebuilt after every rank check.","operationId":"list_keyword_clusters_v1_brands__brand_id__seo_keyword_clusters_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Page size (1-100).","default":20,"title":"Limit"},"description":"Page size (1-100)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Clusters to skip.","default":0,"title":"Offset"},"description":"Clusters to skip."},{"name":"sort","in":"query","required":false,"schema":{"enum":["volume","keywords","position","prompts"],"type":"string","description":"`volume` (default), `keywords`, `position` (best first) or `prompts`.","default":"volume","title":"Sort"},"description":"`volume` (default), `keywords`, `position` (best first) or `prompts`."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned keyword clusters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeywordClusterList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:seo","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/seo/keyword-clusters/recomputes":{"post":{"tags":["SEO keywords"],"summary":"Rebuild keyword clusters","description":"Regroup the library from the Google results and wording already stored. Free: nothing is bought.\n\nClusters group the keyword library into topics: keywords whose Google top 10 shares 3 or more pages with the most searched one (the pillar), and, for keywords without recent Google results, the ones sharing its wording. They are rebuilt after every rank check. Starter plan and up.","operationId":"recompute_keyword_clusters_v1_brands__brand_id__seo_keyword_clusters_recomputes_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Rebuild keyword clusters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeywordClustersRecomputed"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:seo","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/seo/keyword-clusters/serp-checks":{"post":{"tags":["SEO keywords"],"summary":"Check SERPs to group keywords","description":"Buy the Google results of the keywords grouped by wording (one per group of spelling variants, most searched first, as many as fit in the day's rank checks) so the clusters regroup by Google results when they land. Counts as rank checks: 1 credit per 10 keywords. `?dry_run=true` prices it.\n\nClusters group the keyword library into topics: keywords whose Google top 10 shares 3 or more pages with the most searched one (the pillar), and, for keywords without recent Google results, the ones sharing its wording. They are rebuilt after every rank check. Starter plan and up.","operationId":"check_cluster_serps_v1_brands__brand_id__seo_keyword_clusters_serp_checks_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"202":{"description":"Check SERPs to group keywords","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RankChecksQueued"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"402":{"description":"Not enough credits to complete this operation","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"insufficient_credits","message":"Not enough credits to complete this operation"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:seo","x-rankprompt-cost":{"request_units":2,"credits":0},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}}},"/v1/brands/{brand_id}/seo/keywords/tracking":{"patch":{"tags":["SEO keywords"],"summary":"Turn rank tracking on or off","description":"Turn Google rank checks on (`rank_tracked: true`) or off for keywords of the library. Turning them on counts against the plan's tracking cap and answers `402 insufficient_credits` with `details.reason: plan_limit` past it; turning them off keeps them saved, with their history. Nothing is charged.","operationId":"update_keyword_tracking_v1_brands__brand_id__seo_keywords_tracking_patch","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeywordTrackingUpdate"}}}},"responses":{"200":{"description":"Turn rank tracking on or off","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeywordTrackingUpdated"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:seo","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/seo/keywords/candidates":{"get":{"tags":["SEO keywords"],"summary":"List keyword candidates","description":"Keywords worth tracking, from what the account already holds: Search Console queries the site earns impressions for, the keywords behind the brand's AI prompts, and the keywords its domain already ranks for. Nothing is bought.","operationId":"keyword_candidates_v1_brands__brand_id__seo_keywords_candidates_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned keyword candidates","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeywordCandidates"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:seo","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/seo/keywords/{keyword_id}":{"patch":{"tags":["SEO keywords"],"summary":"Update a tracked keyword","description":"Set the page that should rank for the keyword (`target_url`), or clear it with null; star or unstar it (`starred`).","operationId":"update_keyword_v1_brands__brand_id__seo_keywords__keyword_id__patch","parameters":[{"name":"keyword_id","in":"path","required":true,"schema":{"type":"string","description":"Tracked keyword id (UUID).","title":"Keyword Id"},"description":"Tracked keyword id (UUID)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeywordUpdate"}}}},"responses":{"200":{"description":"Updated a tracked keyword","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackedKeyword"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:seo","x-rankprompt-cost":{"request_units":1,"credits":0}},"delete":{"tags":["SEO keywords"],"summary":"Stop tracking a keyword","description":"Stop tracking a keyword. Its rank history goes with it.","operationId":"delete_keyword_v1_brands__brand_id__seo_keywords__keyword_id__delete","parameters":[{"name":"keyword_id","in":"path","required":true,"schema":{"type":"string","description":"Tracked keyword id (UUID).","title":"Keyword Id"},"description":"Tracked keyword id (UUID)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"204":{"description":"Stop tracking a keyword","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:seo","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/seo/keywords/metric-refreshes":{"post":{"tags":["SEO keywords"],"summary":"Refresh keyword numbers","description":"Buy fresh Google search volume, difficulty and intent for tracked keywords (all of them when `keyword_ids` is omitted). Numbers less than a day old are skipped.\n\nCredits are charged per batch, only for what is actually bought, and reported in `credits_charged`: Google numbers 1 credit per batch of keywords, rank checks 1 per 10 keywords, research 1 per seed (free when cached for the day), a domain overview 1 per 5 domains bought, a keyword gap 1 for up to 5 competitors, one site's ranking keywords 1 (free while cached for the week). Every plan can use keywords; the plan caps how many are tracked and how many checks run a day, and a cap answers `402 insufficient_credits` with `details.reason: plan_limit`.","operationId":"refresh_keyword_metrics_v1_brands__brand_id__seo_keywords_metric_refreshes_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/KeywordSelection"},{"type":"null"}],"title":"Body"}}}},"responses":{"200":{"description":"Refresh keyword numbers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricsRefreshed"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"402":{"description":"Not enough credits to complete this operation","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"insufficient_credits","message":"Not enough credits to complete this operation"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:seo","x-rankprompt-cost":{"request_units":2,"credits":0},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}}},"/v1/brands/{brand_id}/seo/keywords/rank-checks":{"post":{"tags":["SEO keywords"],"summary":"Check Google positions","description":"Queue a Google rank check for tracked keywords (all of them when `keyword_ids` is omitted). Keywords checked in the last 20 hours are skipped unless `force` is set. Positions land within minutes: it is not a job, so read the keywords again (`checking` turns false).\n\nCredits are charged per batch, only for what is actually bought, and reported in `credits_charged`: Google numbers 1 credit per batch of keywords, rank checks 1 per 10 keywords, research 1 per seed (free when cached for the day), a domain overview 1 per 5 domains bought, a keyword gap 1 for up to 5 competitors, one site's ranking keywords 1 (free while cached for the week). Every plan can use keywords; the plan caps how many are tracked and how many checks run a day, and a cap answers `402 insufficient_credits` with `details.reason: plan_limit`.","operationId":"check_ranks_v1_brands__brand_id__seo_keywords_rank_checks_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/RankChecksCreate"},{"type":"null"}],"title":"Body"}}}},"responses":{"202":{"description":"Check Google positions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RankChecksQueued"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"402":{"description":"Not enough credits to complete this operation","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"insufficient_credits","message":"Not enough credits to complete this operation"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:seo","x-rankprompt-cost":{"request_units":2,"credits":0},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}}},"/v1/brands/{brand_id}/seo/keywords/{keyword_id}/history":{"get":{"tags":["SEO keywords"],"summary":"Get a keyword's rank history","description":"One keyword with its rank checks, newest first, a page at a time, with who held the top of the results page each time.","operationId":"keyword_history_v1_brands__brand_id__seo_keywords__keyword_id__history_get","parameters":[{"name":"keyword_id","in":"path","required":true,"schema":{"type":"string","description":"Tracked keyword id (UUID).","title":"Keyword Id"},"description":"Tracked keyword id (UUID)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Page size (default 20, max 100).","default":20,"title":"Limit"},"description":"Page size (default 20, max 100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Continuation token from a previous response's `next_cursor`.","title":"Cursor"},"description":"Continuation token from a previous response's `next_cursor`."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned a keyword's rank history","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeywordHistory"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:seo","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/seo/keywords/{keyword_id}/prompts":{"get":{"tags":["SEO keywords"],"summary":"List the AI prompts behind a keyword","description":"The brand's AI prompts that stand for this Google keyword, with how often each ran, how many answers named the brand, and how hard the AI answer is to win. Read with the keyword's position to see whether the brand wins in Google, in the engines, both or neither.\n\nOffset-paginated and counted from the answers at read time: most run first, then most answers, then the prompt text.","operationId":"keyword_prompts_v1_brands__brand_id__seo_keywords__keyword_id__prompts_get","parameters":[{"name":"keyword_id","in":"path","required":true,"schema":{"type":"string","description":"Tracked keyword id (UUID).","title":"Keyword Id"},"description":"Tracked keyword id (UUID)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Page size (1-100).","default":20,"title":"Limit"},"description":"Page size (1-100)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Prompts to skip.","default":0,"title":"Offset"},"description":"Prompts to skip."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned the AI prompts behind a keyword","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeywordPrompts"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:seo","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/seo/keyword-research":{"post":{"tags":["SEO keywords"],"summary":"Research keywords","description":"Keyword ideas, longer phrasings or related searches for a seed, each with search volume, difficulty and intent in the brand's market, flagged when already tracked or off topic.\n\nCredits are charged per batch, only for what is actually bought, and reported in `credits_charged`: Google numbers 1 credit per batch of keywords, rank checks 1 per 10 keywords, research 1 per seed (free when cached for the day), a domain overview 1 per 5 domains bought, a keyword gap 1 for up to 5 competitors, one site's ranking keywords 1 (free while cached for the week). Every plan can use keywords; the plan caps how many are tracked and how many checks run a day, and a cap answers `402 insufficient_credits` with `details.reason: plan_limit`.","operationId":"research_keywords_v1_brands__brand_id__seo_keyword_research_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeywordResearchCreate"}}}},"responses":{"200":{"description":"Research keywords","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeywordResearch"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"402":{"description":"Not enough credits to complete this operation","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"insufficient_credits","message":"Not enough credits to complete this operation"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:seo","x-rankprompt-cost":{"request_units":2,"credits":0},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}}},"/v1/brands/{brand_id}/seo/keyword-metrics/lookups":{"post":{"tags":["SEO keywords"],"summary":"Look up keyword numbers","description":"Google search volume, difficulty, intent and CPC for up to 700 keywords in the brand's market, without tracking them: nothing is saved to the brand. Each row says whether the keyword is already tracked. One credit for the keywords the month's cache does not hold (none when it holds them all), refunded when Google returns nothing.\n\nCredits are charged per batch, only for what is actually bought, and reported in `credits_charged`: Google numbers 1 credit per batch of keywords, rank checks 1 per 10 keywords, research 1 per seed (free when cached for the day), a domain overview 1 per 5 domains bought, a keyword gap 1 for up to 5 competitors, one site's ranking keywords 1 (free while cached for the week). Every plan can use keywords; the plan caps how many are tracked and how many checks run a day, and a cap answers `402 insufficient_credits` with `details.reason: plan_limit`.","operationId":"lookup_keyword_metrics_v1_brands__brand_id__seo_keyword_metrics_lookups_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeywordMetricsLookupCreate"}}}},"responses":{"200":{"description":"Look up keyword numbers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeywordMetricsLookup"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"402":{"description":"Not enough credits to complete this operation","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"insufficient_credits","message":"Not enough credits to complete this operation"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:seo","x-rankprompt-cost":{"request_units":2,"credits":0},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}}},"/v1/brands/{brand_id}/seo/overview":{"get":{"tags":["SEO keywords"],"summary":"Get the Google overview","description":"How the brand's domain and its competitors rank in Google (keywords in the top 3, 10 and 20, estimated traffic and its value), and the keywords the brand's domain ranks for. Reads the weekly cache; `cache` says whether `POST .../seo/overview/refreshes` has anything to buy. Every competitor and ranked keyword comes back unless `competitors_limit`, `limit` or `offset` narrow them; the totals count them all. `min_position` and `max_position` keep the keywords whose best position falls in that band, each once, nearest the top first: 11 to 20 are the keywords just off page one.","operationId":"seo_overview_v1_brands__brand_id__seo_overview_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"competitors_limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":100,"minimum":0},{"type":"null"}],"description":"Keep only this many competitors, most mentioned first.","title":"Competitors Limit"},"description":"Keep only this many competitors, most mentioned first."},{"name":"limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":100,"minimum":1},{"type":"null"}],"description":"Ranked keywords to return.","title":"Limit"},"description":"Ranked keywords to return."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Ranked keywords to skip.","default":0,"title":"Offset"},"description":"Ranked keywords to skip."},{"name":"min_position","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":100,"minimum":1},{"type":"null"}],"description":"Keep ranked keywords whose best position is at least this.","title":"Min Position"},"description":"Keep ranked keywords whose best position is at least this."},{"name":"max_position","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":100,"minimum":1},{"type":"null"}],"description":"Keep ranked keywords whose best position is at most this.","title":"Max Position"},"description":"Keep ranked keywords whose best position is at most this."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned the Google overview","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoOverview"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:seo","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/seo/overview/refreshes":{"post":{"tags":["SEO keywords"],"summary":"Refresh the Google overview","description":"Buy the domain overview of the brand and the picked competitors (`domains`; omit for the four most mentioned) where the weekly cache is missing or stale, and return the overview. Up to 100 domains a refresh. `competitors_limit` trims the competitors returned, as on the read; it never changes what is bought.\n\nCredits are charged per batch, only for what is actually bought, and reported in `credits_charged`: Google numbers 1 credit per batch of keywords, rank checks 1 per 10 keywords, research 1 per seed (free when cached for the day), a domain overview 1 per 5 domains bought, a keyword gap 1 for up to 5 competitors, one site's ranking keywords 1 (free while cached for the week). Every plan can use keywords; the plan caps how many are tracked and how many checks run a day, and a cap answers `402 insufficient_credits` with `details.reason: plan_limit`.","operationId":"refresh_seo_overview_v1_brands__brand_id__seo_overview_refreshes_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"competitors_limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":100,"minimum":0},{"type":"null"}],"description":"Keep only this many competitors, most mentioned first.","title":"Competitors Limit"},"description":"Keep only this many competitors, most mentioned first."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/SeoRefreshCreate"},{"type":"null"}],"title":"Body"}}}},"responses":{"200":{"description":"Refresh the Google overview","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoOverview"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"402":{"description":"Not enough credits to complete this operation","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"insufficient_credits","message":"Not enough credits to complete this operation"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:seo","x-rankprompt-cost":{"request_units":3,"credits":0},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}}},"/v1/brands/{brand_id}/seo/keyword-gap":{"get":{"tags":["SEO keywords"],"summary":"Get the keyword gap","description":"Keywords the brand's competitors rank for in Google's top 20 that the brand's site does not, with each keyword's numbers and which competitors hold it. Reads the weekly cache; `cache` names the competitors `POST .../seo/keyword-gap/refreshes` would fetch. Every competitor and row comes back unless `competitors_limit`, `limit` or `offset` narrow them; the totals count them all.","operationId":"seo_keyword_gap_v1_brands__brand_id__seo_keyword_gap_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"competitors_limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":100,"minimum":0},{"type":"null"}],"description":"Keep only this many competitors, most mentioned first.","title":"Competitors Limit"},"description":"Keep only this many competitors, most mentioned first."},{"name":"limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":100,"minimum":1},{"type":"null"}],"description":"Gap keywords to return.","title":"Limit"},"description":"Gap keywords to return."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Gap keywords to skip.","default":0,"title":"Offset"},"description":"Gap keywords to skip."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned the keyword gap","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeywordGap"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:seo","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/seo/keyword-gap/refreshes":{"post":{"tags":["SEO keywords"],"summary":"Refresh the keyword gap","description":"Buy the keyword gap for the picked competitors (`domains`; omit for the most mentioned few) whose weekly cache is missing or stale, and return the gap. `competitors_limit` trims the competitors and `cache` returned, as on the read; it never changes what is bought.\n\nCredits are charged per batch, only for what is actually bought, and reported in `credits_charged`: Google numbers 1 credit per batch of keywords, rank checks 1 per 10 keywords, research 1 per seed (free when cached for the day), a domain overview 1 per 5 domains bought, a keyword gap 1 for up to 5 competitors, one site's ranking keywords 1 (free while cached for the week). Every plan can use keywords; the plan caps how many are tracked and how many checks run a day, and a cap answers `402 insufficient_credits` with `details.reason: plan_limit`.","operationId":"refresh_seo_keyword_gap_v1_brands__brand_id__seo_keyword_gap_refreshes_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"competitors_limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":100,"minimum":0},{"type":"null"}],"description":"Keep only this many competitors, most mentioned first.","title":"Competitors Limit"},"description":"Keep only this many competitors, most mentioned first."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/SeoRefreshCreate"},{"type":"null"}],"title":"Body"}}}},"responses":{"200":{"description":"Refresh the keyword gap","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeywordGap"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"402":{"description":"Not enough credits to complete this operation","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"insufficient_credits","message":"Not enough credits to complete this operation"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:seo","x-rankprompt-cost":{"request_units":3,"credits":0},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}}},"/v1/brands/{brand_id}/seo/prompt-insights":{"get":{"tags":["SEO keywords"],"summary":"Get prompt insights for a report","description":"For every prompt of a report: the Google keyword it stands for, that keyword's search volume and difficulty, and how hard the AI answer is to win (who keeps winning it and how stable it is). Use it to weigh a gap by real demand before writing for it. Prompts are mapped by a job after the report completes; `pending` counts the ones still waiting. Nothing is bought. A report of another brand is `404 not_found`.","operationId":"prompt_insights_v1_brands__brand_id__seo_prompt_insights_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"report_id","in":"query","required":true,"schema":{"type":"string","description":"Report whose prompts to read.","title":"Report Id"},"description":"Report whose prompts to read."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned prompt insights for a report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromptInsights"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:seo","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/seo/prompt-insights/lookups":{"post":{"tags":["SEO keywords"],"summary":"Look up prompt insights","description":"The same insights for any prompt texts of the brand, across reports and schedules. Nothing is bought. It is a POST because the prompt texts go in the body, so it still takes an `Idempotency-Key`: send a fresh one when you want fresh data, since reusing one replays the stored answer.","operationId":"lookup_prompt_insights_v1_brands__brand_id__seo_prompt_insights_lookups_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromptInsightsLookup"}}}},"responses":{"200":{"description":"Look up prompt insights","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromptInsights"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:seo","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/seo/prompt-insights/keyword":{"put":{"tags":["SEO keywords"],"summary":"Pin the keyword a prompt stands for","description":"Set the Google keyword a prompt stands for when the automatic mapping got it wrong. A pinned mapping is never rewritten. The prompt must already be mapped (its report completed).","operationId":"pin_prompt_keyword_v1_brands__brand_id__seo_prompt_insights_keyword_put","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromptKeywordPin"}}}},"responses":{"200":{"description":"Pin the keyword a prompt stands for","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromptKeywordMapping"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:seo","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/tasks":{"get":{"tags":["Tasks"],"summary":"List tasks","description":"List a brand's tasks, newest first, or with `order_by=priority` high to low, ties by due date (undated last) then newest, as the Tasks page sorts them. Cursor-paginated; a cursor keeps the order it was issued for. Filters (`status`, `category`, `priority`, `assignee_id`, `source_type`, `has_article`, `show_archived`, `search`) compose with AND. Without `status` the list holds accepted work (`backlog` to `done`); ask for `status=suggested` or `status=dismissed` to read those. A suggested task nobody accepts, dismisses or edits for 90 days is deleted nightly; if the finding still applies it comes back as a new suggestion with a new id.","operationId":"list_tasks_v1_brands__brand_id__tasks_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":64},{"type":"null"}],"description":"Filter by status: `suggested`, `backlog`, `in_progress`, `review`, `approved`, `done`, `dismissed`. Omitted: accepted work only.","title":"Status"},"description":"Filter by status: `suggested`, `backlog`, `in_progress`, `review`, `approved`, `done`, `dismissed`. Omitted: accepted work only."},{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"enum":["CONTENT","TECHNICAL","OUTREACH","KNOWLEDGE","MONITORING","SEO","LOCAL"],"type":"string"},{"type":"null"}],"description":"Filter by category: `CONTENT`, `TECHNICAL`, `OUTREACH`, `KNOWLEDGE`, `MONITORING`, `SEO`.","title":"Category"},"description":"Filter by category: `CONTENT`, `TECHNICAL`, `OUTREACH`, `KNOWLEDGE`, `MONITORING`, `SEO`."},{"name":"priority","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":64},{"type":"null"}],"description":"Filter by priority: `high`, `medium`, `low`.","title":"Priority"},"description":"Filter by priority: `high`, `medium`, `low`."},{"name":"assignee_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":64},{"type":"null"}],"description":"Filter by assignee user id.","title":"Assignee Id"},"description":"Filter by assignee user id."},{"name":"source_type","in":"query","required":false,"schema":{"anyOf":[{"enum":["brand_audit","report","seo_audit","technical_audit","manual","content_brief","search_console","content_opportunity","rank_check","gbp_audit","youtube","site_pilot"],"type":"string"},{"type":"null"}],"description":"Filter by what generated the task.","title":"Source Type"},"description":"Filter by what generated the task."},{"name":"has_article","in":"query","required":false,"schema":{"type":"boolean","description":"Only tasks with a linked content brief/article.","default":false,"title":"Has Article"},"description":"Only tasks with a linked content brief/article."},{"name":"show_archived","in":"query","required":false,"schema":{"type":"boolean","description":"Include archived tasks.","default":false,"title":"Show Archived"},"description":"Include archived tasks."},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Case-insensitive substring of the task title.","title":"Search"},"description":"Case-insensitive substring of the task title."},{"name":"place","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","minLength":1,"maxLength":300},"maxItems":200},{"type":"null"}],"description":"Only the tasks made from a run in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake); repeat the parameter for several. A task with no report has no place and is left out.","title":"Place"},"description":"Only the tasks made from a run in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake); repeat the parameter for several. A task with no report has no place and is left out."},{"name":"order_by","in":"query","required":false,"schema":{"enum":["created_at","priority"],"type":"string","description":"`created_at` (default): newest first. `priority`: high, medium, low, then no priority; ties by due date, undated last, then newest.","default":"created_at","title":"Order By"},"description":"`created_at` (default): newest first. `priority`: high, medium, low, then no priority; ties by due date, undated last, then newest."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Page size (default 20, max 100).","default":20,"title":"Limit"},"description":"Page size (default 20, max 100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Continuation token from a previous response's `next_cursor`.","title":"Cursor"},"description":"Continuation token from a previous response's `next_cursor`."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned tasks","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:tasks","x-rankprompt-cost":{"request_units":1,"credits":0}},"post":{"tags":["Tasks"],"summary":"Create a task","description":"Create a work item for the brand. New tasks start in the `backlog` column.","operationId":"create_task_v1_brands__brand_id__tasks_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCreate"}}}},"responses":{"201":{"description":"Created a task","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:tasks","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/tasks/summary":{"get":{"tags":["Tasks"],"summary":"Task counts summary","description":"Aggregated task counts for the brand, bucketed by `status` and `priority`.","operationId":"get_task_summary_v1_brands__brand_id__tasks_summary_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"show_archived","in":"query","required":false,"schema":{"type":"boolean","description":"Include archived tasks in the counts.","default":false,"title":"Show Archived"},"description":"Include archived tasks in the counts."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Task counts summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskSummary"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:tasks","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/tasks/{task_id}":{"get":{"tags":["Tasks"],"summary":"Retrieve a task","description":"One task in full, with `source`: a snapshot of the report, brand audit, SEO pages or article it came from. A client seat reads accepted work only; a suggested or dismissed task answers `404` to it.","operationId":"get_task_v1_brands__brand_id__tasks__task_id__get","parameters":[{"name":"task_id","in":"path","required":true,"schema":{"type":"string","description":"Task id (UUID).","title":"Task Id"},"description":"Task id (UUID)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned a task","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskDetail"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:tasks","x-rankprompt-cost":{"request_units":1,"credits":0}},"patch":{"tags":["Tasks"],"summary":"Update a task","description":"Update a task. Only the fields you send change; send `status` to move it across the board (`backlog` to `in_progress` to `review` to `approved` to `done`). A `suggested` task is accepted by moving it to `backlog` and declined with `dismissed`.","operationId":"update_task_v1_brands__brand_id__tasks__task_id__patch","parameters":[{"name":"task_id","in":"path","required":true,"schema":{"type":"string","description":"Task id (UUID).","title":"Task Id"},"description":"Task id (UUID)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskUpdate"}}}},"responses":{"200":{"description":"Updated a task","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:tasks","x-rankprompt-cost":{"request_units":1,"credits":0}},"delete":{"tags":["Tasks"],"summary":"Delete a task","description":"Permanently delete a task. Requires OWNER access on the brand.","operationId":"delete_task_v1_brands__brand_id__tasks__task_id__delete","parameters":[{"name":"task_id","in":"path","required":true,"schema":{"type":"string","description":"Task id (UUID).","title":"Task Id"},"description":"Task id (UUID)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"204":{"description":"Task deleted.","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:tasks","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/campaigns":{"get":{"tags":["Outreach"],"summary":"List campaigns","description":"The brand's outreach campaigns, newest first, with status and what their emails did. Cursor paginated. A client seat cannot reach campaigns.","operationId":"list_campaigns_v1_brands__brand_id__campaigns_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"enum":["draft","active","paused","completed","archived"],"type":"string"},{"type":"null"}],"description":"`draft`, `active`, `paused`, `completed` or `archived`.","title":"Status"},"description":"`draft`, `active`, `paused`, `completed` or `archived`."},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Substring of the campaign name.","title":"Search"},"description":"Substring of the campaign name."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Page size (default 20, max 100).","default":20,"title":"Limit"},"description":"Page size (default 20, max 100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Continuation token from a previous response's `next_cursor`.","title":"Cursor"},"description":"Continuation token from a previous response's `next_cursor`."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned campaigns","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:outreach","x-rankprompt-cost":{"request_units":1,"credits":0}},"post":{"tags":["Outreach"],"summary":"Create a campaign","description":"Create a campaign as a draft: a contact list, a template or a sequence, the mailbox it sends from, a send window and a daily limit. Nothing is sent until `PATCH` sets `status` to `active`; `GET .../campaigns/{campaign_id}/preview` shows what that would do first. Requires the editor role and the brand owner on Pro. A client seat cannot reach campaigns.","operationId":"create_campaign_v1_brands__brand_id__campaigns_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignCreate"}}}},"responses":{"201":{"description":"Created a campaign","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:outreach","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/campaigns/{campaign_id}":{"get":{"tags":["Outreach"],"summary":"Retrieve a campaign","description":"One campaign with its settings, what its emails did and the next email due. A client seat cannot reach campaigns.","operationId":"get_campaign_v1_brands__brand_id__campaigns__campaign_id__get","parameters":[{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string","description":"Campaign id.","title":"Campaign Id"},"description":"Campaign id."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned a campaign","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:outreach","x-rankprompt-cost":{"request_units":1,"credits":0}},"patch":{"tags":["Outreach"],"summary":"Update, launch, pause or end a campaign","description":"Change a campaign's settings, or its state through `status`:\n\n- `active` launches a draft or resumes a paused campaign. Real emails go out from its mailbox in the send window, within the mailbox's daily limit and warmup, skipping unsubscribed and blocked addresses. A trial sends up to 20 outreach emails in all and the rest wait for the subscription; launching with none left answers `403 brand_plan_required` with `details.reason` `trial_limit`. It needs a connected mailbox (`400 integration_not_connected` with `details.connect_url`).\n- `paused` stops sending until it is active again.\n- `completed` ends it for good; its remaining emails are not sent.\n- `archived` hides a campaign that is not active.\n\nAn active campaign must be paused before its list, emails or mailbox change. The call is the caller's intent: it runs with no confirmation step. Requires the editor role and the brand owner on Pro. A client seat cannot reach campaigns.","operationId":"update_campaign_v1_brands__brand_id__campaigns__campaign_id__patch","parameters":[{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string","description":"Campaign id.","title":"Campaign Id"},"description":"Campaign id."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignUpdate"}}}},"responses":{"200":{"description":"Update, launch, pause or end a campaign","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:outreach","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/campaigns/{campaign_id}/timeline":{"get":{"tags":["Outreach"],"summary":"A campaign's days","description":"A campaign's sends, opens and replies per day. A client seat cannot reach campaigns.","operationId":"get_campaign_timeline_v1_brands__brand_id__campaigns__campaign_id__timeline_get","parameters":[{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string","description":"Campaign id.","title":"Campaign Id"},"description":"Campaign id."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"days","in":"query","required":false,"schema":{"type":"integer","maximum":365,"minimum":1,"description":"Days back from today (1-365, default 30).","default":30,"title":"Days"},"description":"Days back from today (1-365, default 30)."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"A campaign's days","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignTimeline"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:outreach","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/campaigns/{campaign_id}/preview":{"get":{"tags":["Outreach"],"summary":"Preview a campaign's launch","description":"What launching the campaign would do: the mailbox with today's cap and warmup, how many contacts it emails with a sample, its first email filled in for the first contact, and anything that blocks the launch. Sends nothing. Requires the brand owner on Pro. A client seat cannot reach campaigns.","operationId":"preview_campaign_v1_brands__brand_id__campaigns__campaign_id__preview_get","parameters":[{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string","description":"Campaign id.","title":"Campaign Id"},"description":"Campaign id."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Preview a campaign's launch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignPreview"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:outreach","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/contact-lists":{"get":{"tags":["Outreach"],"summary":"List contact lists","description":"The brand's contact lists, static and dynamic, newest first, with how many contacts each holds now. Cursor paginated.","operationId":"list_contact_lists_v1_brands__brand_id__contact_lists_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Substring of the name or description.","title":"Search"},"description":"Substring of the name or description."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Page size (default 20, max 100).","default":20,"title":"Limit"},"description":"Page size (default 20, max 100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Continuation token from a previous response's `next_cursor`.","title":"Cursor"},"description":"Continuation token from a previous response's `next_cursor`."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned contact lists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactListList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:outreach","x-rankprompt-cost":{"request_units":1,"credits":0}},"post":{"tags":["Outreach"],"summary":"Create a contact list","description":"Create a static list (contacts added with `POST .../contact-lists/{list_id}/contacts`) or a dynamic one (`is_dynamic` with `segment_filters`, at least one condition) that follows its filter as contacts change. `POST .../contact-lists/previews` tries a filter first. Requires the editor role and the brand owner on Pro.","operationId":"create_contact_list_v1_brands__brand_id__contact_lists_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactListCreate"}}}},"responses":{"201":{"description":"Created a contact list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:outreach","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/contact-lists/previews":{"post":{"tags":["Outreach"],"summary":"Preview a dynamic list's filter","description":"Count the contacts a dynamic list's filter matches now, with a sample, before saving it. Saves nothing. Requires the editor role and the brand owner on Pro.","operationId":"preview_contact_filter_v1_brands__brand_id__contact_lists_previews_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactFilterPreviewCreate"}}}},"responses":{"200":{"description":"Preview a dynamic list's filter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactFilterPreview"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:outreach","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/contact-lists/{list_id}":{"get":{"tags":["Outreach"],"summary":"Retrieve a contact list","description":"One contact list with how many contacts it holds now.","operationId":"get_contact_list_v1_brands__brand_id__contact_lists__list_id__get","parameters":[{"name":"list_id","in":"path","required":true,"schema":{"type":"string","description":"Contact list id.","title":"List Id"},"description":"Contact list id."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned a contact list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:outreach","x-rankprompt-cost":{"request_units":1,"credits":0}},"patch":{"tags":["Outreach"],"summary":"Update a contact list","description":"Rename a list, change its description, or change a dynamic list's filter. Requires the editor role and the brand owner on Pro.","operationId":"update_contact_list_v1_brands__brand_id__contact_lists__list_id__patch","parameters":[{"name":"list_id","in":"path","required":true,"schema":{"type":"string","description":"Contact list id.","title":"List Id"},"description":"Contact list id."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactListUpdate"}}}},"responses":{"200":{"description":"Updated a contact list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:outreach","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/contact-lists/{list_id}/contacts":{"get":{"tags":["Outreach"],"summary":"List a contact list's contacts","description":"The contacts on a list now, each with the cited page it was added with (what `{{page_url}}`, `{{page_title}}` and `{{role}}` fill). A dynamic list's members are matched at read time, so the list pages by `limit` and `offset` and returns `total`.","operationId":"list_contact_list_members_v1_brands__brand_id__contact_lists__list_id__contacts_get","parameters":[{"name":"list_id","in":"path","required":true,"schema":{"type":"string","description":"Contact list id.","title":"List Id"},"description":"Contact list id."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Substring of the name or email.","title":"Search"},"description":"Substring of the name or email."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Contacts per page (1-100, default 20).","default":20,"title":"Limit"},"description":"Contacts per page (1-100, default 20)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Contacts to skip from the start.","default":0,"title":"Offset"},"description":"Contacts to skip from the start."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned a contact list's contacts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactListMemberList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:outreach","x-rankprompt-cost":{"request_units":1,"credits":0}},"post":{"tags":["Outreach"],"summary":"Add contacts to a static list","description":"Add up to 500 contacts to a static list. Send `contacts_with_pages` (each contact with the `citation_contact_id` of the page it was found on, from `GET .../contacts/{contact_id}/citations`) so the list's emails can name the page. Contacts already on the list are skipped; a dynamic list is refused. Requires the editor role and the brand owner on Pro.","operationId":"add_contact_list_members_v1_brands__brand_id__contact_lists__list_id__contacts_post","parameters":[{"name":"list_id","in":"path","required":true,"schema":{"type":"string","description":"Contact list id.","title":"List Id"},"description":"Contact list id."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactListMembersAdd"}}}},"responses":{"200":{"description":"Add contacts to a static list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactListMembersAdded"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:outreach","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/contact-lists/{list_id}/contacts/{contact_id}":{"delete":{"tags":["Outreach"],"summary":"Remove a contact from a static list","description":"Take one contact off a static list; the contact itself stays. Requires the editor role, on any plan.","operationId":"remove_contact_list_member_v1_brands__brand_id__contact_lists__list_id__contacts__contact_id__delete","parameters":[{"name":"list_id","in":"path","required":true,"schema":{"type":"string","description":"Contact list id.","title":"List Id"},"description":"Contact list id."},{"name":"contact_id","in":"path","required":true,"schema":{"type":"string","description":"Contact id.","title":"Contact Id"},"description":"Contact id."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"204":{"description":"Contact removed from the list.","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:outreach","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/contacts":{"get":{"tags":["Outreach"],"summary":"List outreach contacts","description":"The brand's outreach contacts, newest first: authors and editors found on cited pages, or added by hand, with their best tier, tags and what the emails to them did. Filters compose with AND. The tier is computed from the pages at read time, so the list pages by `limit` and `offset` and returns `total`. A client seat cannot reach contacts.","operationId":"list_contacts_v1_brands__brand_id__contacts_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Substring of the name or email.","title":"Search"},"description":"Substring of the name or email."},{"name":"tags","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":20},{"type":"null"}],"description":"Contacts holding every one of these tags; repeat it.","title":"Tags"},"description":"Contacts holding every one of these tags; repeat it."},{"name":"best_tier","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":6,"minimum":1},{"type":"null"}],"description":"Only contacts whose best tier is this.","title":"Best Tier"},"description":"Only contacts whose best tier is this."},{"name":"has_email","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"`true`: only contacts with an email.","title":"Has Email"},"description":"`true`: only contacts with an email."},{"name":"email_verified","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter by a verified email.","title":"Email Verified"},"description":"Filter by a verified email."},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"enum":["active","unsubscribed","bounced"],"type":"string"},{"type":"null"}],"description":"`active`, `unsubscribed` or `bounced`.","title":"Status"},"description":"`active`, `unsubscribed` or `bounced`."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Contacts per page (1-100, default 20).","default":20,"title":"Limit"},"description":"Contacts per page (1-100, default 20)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Contacts to skip from the start.","default":0,"title":"Offset"},"description":"Contacts to skip from the start."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned outreach contacts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contacts"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:outreach","x-rankprompt-cost":{"request_units":1,"credits":0}},"post":{"tags":["Outreach"],"summary":"Add an outreach contact","description":"Add a contact by hand. It needs at least an email, a name, a LinkedIn URL or an X handle. An email that is unsubscribed, on a blocked domain or already a contact is refused. Requires the editor role. Requires the brand owner on Pro. A client seat cannot reach contacts.","operationId":"create_contact_v1_brands__brand_id__contacts_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactCreate"}}}},"responses":{"201":{"description":"Add an outreach contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:outreach","x-rankprompt-cost":{"request_units":1,"credits":0}},"patch":{"tags":["Outreach"],"summary":"Tag several contacts","description":"Add or remove tags on up to 100 contacts at once, to group them for a dynamic list. Requires the editor role. Requires the brand owner on Pro. A client seat cannot reach contacts.","operationId":"tag_contacts_v1_brands__brand_id__contacts_patch","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactTagging"}}}},"responses":{"200":{"description":"Tag several contacts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactTaggingResult"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:outreach","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/contacts/{contact_id}":{"get":{"tags":["Outreach"],"summary":"Retrieve an outreach contact","description":"One contact with its best tier, tags, the static lists it is on, what the emails to it did and its last 50 sends, opens and replies. A client seat cannot reach contacts.","operationId":"get_contact_v1_brands__brand_id__contacts__contact_id__get","parameters":[{"name":"contact_id","in":"path","required":true,"schema":{"type":"string","description":"Contact id.","title":"Contact Id"},"description":"Contact id."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned an outreach contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactDetail"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:outreach","x-rankprompt-cost":{"request_units":1,"credits":0}},"patch":{"tags":["Outreach"],"summary":"Update an outreach contact","description":"Change a contact's name, company, website, LinkedIn URL or X handle, or replace its tags. Only the fields sent change; the email cannot. Requires the editor role. Requires the brand owner on Pro. A client seat cannot reach contacts.","operationId":"update_contact_v1_brands__brand_id__contacts__contact_id__patch","parameters":[{"name":"contact_id","in":"path","required":true,"schema":{"type":"string","description":"Contact id.","title":"Contact Id"},"description":"Contact id."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactUpdate"}}}},"responses":{"200":{"description":"Updated an outreach contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:outreach","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/contacts/{contact_id}/citations":{"get":{"tags":["Outreach"],"summary":"List the pages a contact was found on","description":"The cited pages a contact was found on, best tier first, with their role on each. Pass a page's `citation_contact_id` to `POST .../contact-lists/{list_id}/contacts` so the list's emails name the page. Pages by `limit` and `offset`. A client seat cannot reach contacts.","operationId":"list_contact_pages_v1_brands__brand_id__contacts__contact_id__citations_get","parameters":[{"name":"contact_id","in":"path","required":true,"schema":{"type":"string","description":"Contact id.","title":"Contact Id"},"description":"Contact id."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Pages per page (1-100, default 20).","default":20,"title":"Limit"},"description":"Pages per page (1-100, default 20)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Pages to skip from the start.","default":0,"title":"Offset"},"description":"Pages to skip from the start."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned the pages a contact was found on","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactPages"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:outreach","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/email-sequences":{"get":{"tags":["Outreach"],"summary":"List email sequences","description":"The brand's email sequences, newest first, with their steps. Cursor paginated.","operationId":"list_email_sequences_v1_brands__brand_id__email_sequences_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Page size (default 20, max 100).","default":20,"title":"Limit"},"description":"Page size (default 20, max 100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Continuation token from a previous response's `next_cursor`.","title":"Cursor"},"description":"Continuation token from a previous response's `next_cursor`."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned email sequences","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailSequenceList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:outreach","x-rankprompt-cost":{"request_units":1,"credits":0}},"post":{"tags":["Outreach"],"summary":"Create an email sequence","description":"Create a sequence: a first email, waits, and follow-ups that branch on opens or replies. Templates come from `GET .../email-templates`. Email steps send a template, wait steps wait some days, and condition steps branch on whether the last email was opened or replied to within a timeout; the first step must be an email. Requires the editor role and the brand owner on Pro.","operationId":"create_email_sequence_v1_brands__brand_id__email_sequences_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailSequenceCreate"}}}},"responses":{"201":{"description":"Created an email sequence","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailSequence"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:outreach","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/email-sequences/{sequence_id}":{"get":{"tags":["Outreach"],"summary":"Retrieve an email sequence","description":"One sequence with its steps, its templates' names, and how each step performs: emails that reached it, went out, were opened or replied to, and how each condition split.","operationId":"get_email_sequence_v1_brands__brand_id__email_sequences__sequence_id__get","parameters":[{"name":"sequence_id","in":"path","required":true,"schema":{"type":"string","description":"Sequence id.","title":"Sequence Id"},"description":"Sequence id."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned an email sequence","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailSequenceDetail"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:outreach","x-rankprompt-cost":{"request_units":1,"credits":0}},"patch":{"tags":["Outreach"],"summary":"Update an email sequence","description":"Rename a sequence or replace its steps (send the full list). A sequence an active campaign uses must stay complete. Email steps send a template, wait steps wait some days, and condition steps branch on whether the last email was opened or replied to within a timeout; the first step must be an email. Requires the editor role and the brand owner on Pro.","operationId":"update_email_sequence_v1_brands__brand_id__email_sequences__sequence_id__patch","parameters":[{"name":"sequence_id","in":"path","required":true,"schema":{"type":"string","description":"Sequence id.","title":"Sequence Id"},"description":"Sequence id."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailSequenceUpdate"}}}},"responses":{"200":{"description":"Updated an email sequence","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailSequence"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:outreach","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/email-sequences/{sequence_id}/variants":{"get":{"tags":["Outreach"],"summary":"List a sequence's A/B variants","description":"Every A/B variant of the sequence's email steps, with how each performs.","operationId":"list_email_variants_v1_brands__brand_id__email_sequences__sequence_id__variants_get","parameters":[{"name":"sequence_id","in":"path","required":true,"schema":{"type":"string","description":"Sequence id.","title":"Sequence Id"},"description":"Sequence id."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned a sequence's A/B variants","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailVariantList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:outreach","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/email-sequences/{sequence_id}/steps/{step_id}/variants":{"post":{"tags":["Outreach"],"summary":"Add an A/B variant to a step","description":"Add an A/B variant to one email step: another template, subject or body, and the share of the step's contacts that get it. The step needs a template first, and the step's variants sum to 100 percent at most. Requires the editor role and the brand owner on Pro.","operationId":"create_email_variant_v1_brands__brand_id__email_sequences__sequence_id__steps__step_id__variants_post","parameters":[{"name":"sequence_id","in":"path","required":true,"schema":{"type":"string","description":"Sequence id.","title":"Sequence Id"},"description":"Sequence id."},{"name":"step_id","in":"path","required":true,"schema":{"type":"string","maxLength":100,"description":"The email step's id, from the sequence's `steps`.","title":"Step Id"},"description":"The email step's id, from the sequence's `steps`."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailVariantCreate"}}}},"responses":{"201":{"description":"Add an A/B variant to a step","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailVariant"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:outreach","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/email-sequences/{sequence_id}/variants/{variant_id}":{"patch":{"tags":["Outreach"],"summary":"Update an A/B variant","description":"Change a variant's content or traffic share, or send `is_winner: true` to declare it the winner: it then gets all of the step's contacts. Requires the editor role and the brand owner on Pro.","operationId":"update_email_variant_v1_brands__brand_id__email_sequences__sequence_id__variants__variant_id__patch","parameters":[{"name":"sequence_id","in":"path","required":true,"schema":{"type":"string","description":"Sequence id.","title":"Sequence Id"},"description":"Sequence id."},{"name":"variant_id","in":"path","required":true,"schema":{"type":"string","description":"Variant id.","title":"Variant Id"},"description":"Variant id."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailVariantUpdate"}}}},"responses":{"200":{"description":"Updated an A/B variant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailVariant"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:outreach","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/email-templates":{"get":{"tags":["Outreach"],"summary":"List email templates","description":"The brand's email templates, newest first, with subject and body. Cursor paginated.","operationId":"list_email_templates_v1_brands__brand_id__email_templates_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"template_type","in":"query","required":false,"schema":{"anyOf":[{"enum":["request_backlink","request_inclusion","build_relationship","follow_up","pitch"],"type":"string"},{"type":"null"}],"description":"Only templates of this type.","title":"Template Type"},"description":"Only templates of this type."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Page size (default 20, max 100).","default":20,"title":"Limit"},"description":"Page size (default 20, max 100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Continuation token from a previous response's `next_cursor`.","title":"Cursor"},"description":"Continuation token from a previous response's `next_cursor`."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned email templates","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplateList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:outreach","x-rankprompt-cost":{"request_units":1,"credits":0}},"post":{"tags":["Outreach"],"summary":"Create an email template","description":"Save an email template for campaigns and sequence steps. Placeholders filled per contact: `{{first_name}}`, `{{name}}`, `{{email}}`, `{{company}}`, `{{brand_name}}`, and from the cited page a contact was added with `{{page_url}}`, `{{page_title}}`, `{{role}}`. Requires the editor role and the brand owner on Pro.","operationId":"create_email_template_v1_brands__brand_id__email_templates_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplateCreate"}}}},"responses":{"201":{"description":"Created an email template","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplate"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:outreach","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/email-templates/{template_id}":{"patch":{"tags":["Outreach"],"summary":"Update an email template","description":"Change a template's name, type, subject or body, or make it the default of its type. Only the fields sent change. Requires the editor role and the brand owner on Pro.","operationId":"update_email_template_v1_brands__brand_id__email_templates__template_id__patch","parameters":[{"name":"template_id","in":"path","required":true,"schema":{"type":"string","description":"Template id.","title":"Template Id"},"description":"Template id."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplateUpdate"}}}},"responses":{"200":{"description":"Updated an email template","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplate"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:outreach","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/emails":{"get":{"tags":["Outreach"],"summary":"List outreach emails","description":"The brand's outreach emails, newest first: drafts, queued, sent, opened, replied and bounced. Filters compose with AND. Cursor paginated; `GET .../emails/summary` counts them. A client seat cannot reach emails.","operationId":"list_emails_v1_brands__brand_id__emails_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"enum":["draft","scheduled","sent","opened","replied","bounced","failed","unsubscribed"],"type":"string"},{"type":"null"}],"description":"One of `draft`, `scheduled`, `sent`, `opened`, `replied`, `bounced`, `failed`, `unsubscribed`.","title":"Status"},"description":"One of `draft`, `scheduled`, `sent`, `opened`, `replied`, `bounced`, `failed`, `unsubscribed`."},{"name":"campaign_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only the emails of this campaign.","title":"Campaign Id"},"description":"Only the emails of this campaign."},{"name":"has_replies","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"`true`: only replied emails; `false`: the rest.","title":"Has Replies"},"description":"`true`: only replied emails; `false`: the rest."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Page size (default 20, max 100).","default":20,"title":"Limit"},"description":"Page size (default 20, max 100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Continuation token from a previous response's `next_cursor`.","title":"Cursor"},"description":"Continuation token from a previous response's `next_cursor`."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned outreach emails","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:outreach","x-rankprompt-cost":{"request_units":1,"credits":0}},"post":{"tags":["Outreach"],"summary":"Save an outreach email draft","description":"Save an email written by hand as a draft. Nothing is sent; `POST .../emails/{email_id}/sends` sends it. An unsubscribed recipient or a blocked domain is refused. Requires the editor role and the brand owner on Pro. A client seat cannot reach emails.","operationId":"create_email_v1_brands__brand_id__emails_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailCreate"}}}},"responses":{"201":{"description":"Save an outreach email draft","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Email"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:outreach","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/emails/summary":{"get":{"tags":["Outreach"],"summary":"Outreach email counts","description":"The brand's outreach emails counted by status, with lifetime open, reply and bounce rates. A client seat cannot reach emails.","operationId":"get_email_summary_v1_brands__brand_id__emails_summary_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Outreach email counts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailSummary"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:outreach","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/emails/ai-compositions":{"post":{"tags":["Outreach"],"summary":"Write a pitch with AI","description":"Write a pitch email with AI (a backlink request, an inclusion in a list, a relationship, a follow-up) from what was learned about the cited page and the brand, and save it as a draft for review. Nothing is sent. **Pricing:** 1 credit per pitch, charged to the brand owner and refunded when the writing fails. Requires the editor role and the brand owner on Pro. A client seat cannot reach emails.","operationId":"compose_email_v1_brands__brand_id__emails_ai_compositions_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailComposition"}}}},"responses":{"201":{"description":"Write a pitch with AI","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Email"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"402":{"description":"Not enough credits to complete this operation","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"insufficient_credits","message":"Not enough credits to complete this operation"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:outreach","x-rankprompt-cost":{"request_units":1,"credits":1},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}}},"/v1/brands/{brand_id}/emails/replies":{"get":{"tags":["Outreach"],"summary":"List outreach replies","description":"The replies the brand's outreach got (the inbox), newest first, each with the email it answers. Cursor paginated. A client seat cannot reach emails.","operationId":"list_email_replies_v1_brands__brand_id__emails_replies_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"unread_only","in":"query","required":false,"schema":{"type":"boolean","description":"Only replies nobody read in the app yet.","default":false,"title":"Unread Only"},"description":"Only replies nobody read in the app yet."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Page size (default 20, max 100).","default":20,"title":"Limit"},"description":"Page size (default 20, max 100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Continuation token from a previous response's `next_cursor`.","title":"Cursor"},"description":"Continuation token from a previous response's `next_cursor`."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned outreach replies","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailReplyList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:outreach","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/emails/{email_id}":{"get":{"tags":["Outreach"],"summary":"Retrieve an outreach email","description":"One outreach email with its status and what it got. A client seat cannot reach emails.","operationId":"get_email_v1_brands__brand_id__emails__email_id__get","parameters":[{"name":"email_id","in":"path","required":true,"schema":{"type":"string","description":"Email id.","title":"Email Id"},"description":"Email id."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned an outreach email","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Email"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:outreach","x-rankprompt-cost":{"request_units":1,"credits":0}},"patch":{"tags":["Outreach"],"summary":"Update an outreach email","description":"Edit a draft or queued email's recipient, subject, HTML body or mailbox; the plain-text body follows the HTML. A sent email cannot change. Requires the editor role and the brand owner on Pro. A client seat cannot reach emails.","operationId":"update_email_v1_brands__brand_id__emails__email_id__patch","parameters":[{"name":"email_id","in":"path","required":true,"schema":{"type":"string","description":"Email id.","title":"Email Id"},"description":"Email id."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailUpdate"}}}},"responses":{"200":{"description":"Updated an outreach email","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Email"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:outreach","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/emails/{email_id}/thread":{"get":{"tags":["Outreach"],"summary":"Read an email's thread","description":"A whole conversation: every email sent in the thread and every reply, oldest first. A client seat cannot reach emails.","operationId":"get_email_thread_v1_brands__brand_id__emails__email_id__thread_get","parameters":[{"name":"email_id","in":"path","required":true,"schema":{"type":"string","description":"Email id.","title":"Email Id"},"description":"Email id."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Read an email's thread","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailThread"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:outreach","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/emails/{email_id}/reply-drafts":{"post":{"tags":["Outreach"],"summary":"Draft a reply in a thread","description":"Save a reply in the email's thread as a draft, to the same recipient and from the thread's mailbox, with the body written as plain text. Nothing is sent; `POST .../emails/{email_id}/sends` on the new draft sends it. Requires the editor role and the brand owner on Pro. A client seat cannot reach emails.","operationId":"create_reply_draft_v1_brands__brand_id__emails__email_id__reply_drafts_post","parameters":[{"name":"email_id","in":"path","required":true,"schema":{"type":"string","description":"Email id.","title":"Email Id"},"description":"Email id."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailReplyDraftCreate"}}}},"responses":{"201":{"description":"Draft a reply in a thread","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Email"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:outreach","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/emails/{email_id}/sends":{"post":{"tags":["Outreach"],"summary":"Send an outreach email","description":"Send a draft (an email or a reply) from a mailbox (Gmail or Outlook) now or at `send_at`: the mailbox named, else the one the email was saved with, else the default, else the only one. It is queued (`status` `scheduled`) and goes out within a few minutes of its time, inside the mailbox's daily limit; unsubscribed and blocked addresses are refused. A trial sends up to 20 outreach emails in all and the rest wait for the subscription; sending with none left answers `403 brand_plan_required` with `details.reason` `trial_limit`. It needs a connected mailbox (`400 integration_not_connected` with `details.connect_url`). It is a real email: the call is the caller's intent and runs with no confirmation step. Requires the editor role and the brand owner on Pro. A client seat cannot reach emails.","operationId":"send_email_v1_brands__brand_id__emails__email_id__sends_post","parameters":[{"name":"email_id","in":"path","required":true,"schema":{"type":"string","description":"Email id.","title":"Email Id"},"description":"Email id."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailSend"}}}},"responses":{"202":{"description":"Email queued to go out.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Email"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:outreach","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/me/mailboxes":{"get":{"tags":["Outreach"],"summary":"List mailboxes","description":"The account's mailboxes outreach sends from (Gmail, or Outlook and Microsoft 365): the provider, whether each still works or needs reconnecting, the default, the daily limit, today's cap while warming up, and how many it sent today. Open to every plan. Mailboxes belong to the account the key acts in, so a key restricted to one brand, or a member limited to some brands, is refused with `403 forbidden`; an account under the plan answers `403 account_plan_required`.","operationId":"list_mailboxes_v1_me_mailboxes_get","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned mailboxes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:outreach","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/me/mailbox-connection-links":{"post":{"tags":["Outreach"],"summary":"Mint a link that connects a mailbox","description":"Return the link that connects or reconnects a mailbox: `provider` `gmail` (the default) or `outlook` for Outlook.com and Microsoft 365. Both need the provider's consent screen, so a person opens it signed in to Rank Prompt with this key's account selected; the page stores the mailbox, with nothing to send back here. Poll `GET /v1/me/mailboxes` until it lists the mailbox as `connected`. Requires an editor over every brand of an account on Pro. Mailboxes belong to the account the key acts in, so a key restricted to one brand, or a member limited to some brands, is refused with `403 forbidden`; an account under the plan answers `403 account_plan_required`.","operationId":"create_mailbox_connection_link_v1_me_mailbox_connection_links_post","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxConnectionLinkCreate"}}}},"responses":{"201":{"description":"Mint a link that connects a mailbox","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxConnectionLink"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:outreach","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/me/mailboxes/{mailbox_id}":{"patch":{"tags":["Outreach"],"summary":"Update a mailbox","description":"Change a mailbox's daily send limit (1 to 500), turn warmup on or off, set its signature or sender name, or make it the default. Requires an editor over every brand of an account on Pro. Mailboxes belong to the account the key acts in, so a key restricted to one brand, or a member limited to some brands, is refused with `403 forbidden`; an account under the plan answers `403 account_plan_required`.","operationId":"update_mailbox_v1_me_mailboxes__mailbox_id__patch","parameters":[{"name":"mailbox_id","in":"path","required":true,"schema":{"type":"string","description":"Mailbox id, from `GET /v1/me/mailboxes`.","title":"Mailbox Id"},"description":"Mailbox id, from `GET /v1/me/mailboxes`."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxUpdate"}}}},"responses":{"200":{"description":"Updated a mailbox","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Mailbox"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:outreach","x-rankprompt-cost":{"request_units":1,"credits":0}},"delete":{"tags":["Outreach"],"summary":"Disconnect a mailbox","description":"Disconnect a mailbox. Refused with `409 conflict` while an active campaign or a scheduled or draft email uses it. Open to every plan, so a downgraded account can still remove its mailboxes; requires an editor over every brand of the account. The call is the caller's intent: it runs with no confirmation step. Mailboxes belong to the account the key acts in, so a key restricted to one brand, or a member limited to some brands, is refused with `403 forbidden`; an account under the plan answers `403 account_plan_required`.","operationId":"delete_mailbox_v1_me_mailboxes__mailbox_id__delete","parameters":[{"name":"mailbox_id","in":"path","required":true,"schema":{"type":"string","description":"Mailbox id, from `GET /v1/me/mailboxes`.","title":"Mailbox Id"},"description":"Mailbox id, from `GET /v1/me/mailboxes`."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"204":{"description":"Mailbox disconnected.","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:outreach","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/outreach/citations":{"post":{"tags":["Outreach"],"summary":"Add pages to Backlink outreach","description":"Add pages as outreach targets: pages AI engines cite that are not there yet, or any page worth pitching. Free. Pages already there are skipped, and new ones are categorized on their own a few minutes later. They then list in `GET /v1/brands/{brand_id}/citations`. Requires the editor role on the brand and the brand owner on Starter or with an active API subscription.","operationId":"add_outreach_targets_v1_brands__brand_id__outreach_citations_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutreachTargetsCreate"}}}},"responses":{"201":{"description":"Add pages to Backlink outreach","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutreachTargetsAdded"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:outreach","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/outreach/citations/{citation_id}":{"patch":{"tags":["Outreach"],"summary":"Set a cited page's contact","description":"Set a cited page's primary contact by hand: the author's name, email or both. The contact is created, or found by its email, and linked to the page as its primary contact. Requires the editor role on the brand and the brand owner on Starter or with an active API subscription.","operationId":"set_outreach_page_contact_v1_brands__brand_id__outreach_citations__citation_id__patch","parameters":[{"name":"citation_id","in":"path","required":true,"schema":{"type":"string","description":"The cited page's id, as `GET /v1/brands/{brand_id}/citations` lists it.","title":"Citation Id"},"description":"The cited page's id, as `GET /v1/brands/{brand_id}/citations` lists it."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutreachPageContactUpdate"}}}},"responses":{"200":{"description":"Set a cited page's contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutreachPageContact"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:outreach","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/outreach/citations/{citation_id}/backlink-verifications":{"post":{"tags":["Outreach"],"summary":"Check a cited page for a backlink","description":"Read a cited page now and say whether it links to the brand's site, with the anchor text and the link's `rel` flags. Run it after a pitch lands. **Pricing:** 1 credit per check, charged to the brand owner and refunded when the page cannot be read. Requires the editor role on the brand and the brand owner on Starter or with an active API subscription.","operationId":"verify_outreach_backlink_v1_brands__brand_id__outreach_citations__citation_id__backlink_verifications_post","parameters":[{"name":"citation_id","in":"path","required":true,"schema":{"type":"string","description":"The cited page's id, as `GET /v1/brands/{brand_id}/citations` lists it.","title":"Citation Id"},"description":"The cited page's id, as `GET /v1/brands/{brand_id}/citations` lists it."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Check a cited page for a backlink","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BacklinkVerification"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"402":{"description":"Not enough credits to complete this operation","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"insufficient_credits","message":"Not enough credits to complete this operation"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:outreach","x-rankprompt-cost":{"request_units":1,"credits":1},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}}},"/v1/brands/{brand_id}/outreach/processing-jobs":{"post":{"tags":["Outreach"],"summary":"Analyze cited pages for outreach","description":"Read cited pages for outreach: who wrote them and their contacts, whether they link to the brand, and which brands they name. Runs in the background: poll `GET /v1/jobs/{job_id}`, then read the contacts with `GET /v1/brands/{brand_id}/contacts`.\n\n**Pricing:** one credit per three pages, charged to the brand owner when the job starts; pages already analyzed with their contacts settled are left out before pricing. `?dry_run=true` quotes the batch at most; a call the balance cannot cover answers `402 insufficient_credits` before anything is queued. Requires the editor role on the brand and the brand owner on Starter or with an active API subscription.","operationId":"analyze_outreach_pages_v1_brands__brand_id__outreach_processing_jobs_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutreachAnalysisCreate"}}}},"responses":{"202":{"description":"Analysis queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutreachAnalysisDispatched"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"402":{"description":"Not enough credits to complete this operation","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"insufficient_credits","message":"Not enough credits to complete this operation"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:outreach","x-rankprompt-cost":{"request_units":1,"credits":0},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}}},"/v1/brands/{brand_id}/outreach/authors":{"get":{"tags":["Outreach"],"summary":"List the most cited authors","description":"The page authors with a contact whose pages the answers cite most, the people worth pitching: the same read as the Authors table of Sources with only the authors a page analysis or a contact search found. Bylines without a contact are in `GET /v1/brands/{brand_id}/citations/authors`. Filters compose with AND: `report_id` (repeat for several), `scheduled_report_id`, `platform` (repeat for several engines), `date_from`, `date_to`, `category` and `search` (the name, email or company). `sort`: `citations` (default), `pages`, `prompts` or `last_seen`. Grouped from the answers at read time, so it pages by `limit` and `offset` and returns `total`.","operationId":"list_outreach_authors_v1_brands__brand_id__outreach_authors_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Words in the name, email or company.","title":"Search"},"description":"Words in the name, email or company."},{"name":"sort","in":"query","required":false,"schema":{"enum":["citations","pages","prompts","last_seen"],"type":"string","description":"Order of the rows.","default":"citations","title":"Sort"},"description":"Order of the rows."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Authors per page (1-100, default 20).","default":20,"title":"Limit"},"description":"Authors per page (1-100, default 20)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Authors to skip from the start.","default":0,"title":"Offset"},"description":"Authors to skip from the start."},{"name":"report_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Only these reports (UUIDs); repeat the parameter for several.","title":"Report Id"},"description":"Only these reports (UUIDs); repeat the parameter for several."},{"name":"report_scope","in":"query","required":false,"schema":{"anyOf":[{"const":"all","type":"string"},{"type":"null"}],"description":"`all` for every completed report of the brand, in place of naming each one; the other filters still apply.","title":"Report Scope"},"description":"`all` for every completed report of the brand, in place of naming each one; the other filters still apply."},{"name":"scheduled_report_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only the runs of this Scheduled Report (UUID).","title":"Scheduled Report Id"},"description":"Only the runs of this Scheduled Report (UUID)."},{"name":"tracker_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":200},{"type":"null"}],"description":"Only the runs of these trackers (a report's `tracker_id`; a scheduled report's id is its tracker's); repeat the parameter for several.","title":"Tracker Id"},"description":"Only the runs of these trackers (a report's `tracker_id`; a scheduled report's id is its tracker's); repeat the parameter for several."},{"name":"market_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":200},{"type":"null"}],"description":"Only the runs in these markets (a report's `market_id`, a region config's `id`); repeat the parameter for several.","title":"Market Id"},"description":"Only the runs in these markets (a report's `market_id`, a region config's `id`); repeat the parameter for several."},{"name":"place","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","minLength":1,"maxLength":300},"maxItems":200},{"type":"null"}],"description":"Only the runs in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake, `australia|emerald|victoria`), across every tracker; repeat the parameter for several.","title":"Place"},"description":"Only the runs in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake, `australia|emerald|victoria`), across every tracker; repeat the parameter for several."},{"name":"scope","in":"query","required":false,"schema":{"anyOf":[{"enum":["default","all"],"type":"string"},{"type":"null"}],"description":"`default` reads what the app opens on (every scheduled report's runs plus the newest one-off reports) and takes no other report, tracker, market or place filter; `all` reads every completed report of the brand.","title":"Scope"},"description":"`default` reads what the app opens on (every scheduled report's runs plus the newest one-off reports) and takes no other report, tracker, market or place filter; `all` reads every completed report of the brand."},{"name":"platform","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"enum":["chatgpt","chatgpt_search","perplexity","ai_overviews","claude","claude_search","gemini","grok","muse"],"type":"string"}},{"type":"null"}],"description":"Only answers from these engines; repeat the parameter for several.","title":"Platform"},"description":"Only answers from these engines; repeat the parameter for several."},{"name":"date_from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only answers from this moment on (ISO-8601).","title":"Date From"},"description":"Only answers from this moment on (ISO-8601)."},{"name":"date_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only answers before this moment, exclusive (ISO-8601); not before `date_from`.","title":"Date To"},"description":"Only answers before this moment, exclusive (ISO-8601); not before `date_from`."},{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","maxLength":200},"maxItems":50},{"type":"null"}],"description":"Only answers to prompts of these categories; repeat the parameter for several.","title":"Category"},"description":"Only answers to prompts of these categories; repeat the parameter for several."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned the most cited authors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutreachAuthorList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:outreach","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/analytics/connection":{"get":{"tags":["Analytics"],"summary":"Get Google connection status","description":"Return the status of the brand's stored Google connection: the overall `status`, the per-service booleans (`google_analytics`, `search_console`, `business_profile`), and the selected `ga4_property_id` / `gsc_site_url`. When no Google account is linked this returns a `not_connected` status with all services `false` rather than an error. No filters; single object.","operationId":"get_analytics_connection_v1_brands__brand_id__analytics_connection_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned Google connection status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsConnection"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:analytics","x-rankprompt-cost":{"request_units":1,"credits":0}},"patch":{"tags":["Analytics"],"summary":"Pick the property and the site","description":"Choose which GA4 property and which Search Console site the brand reads, from `GET /v1/brands/{brand_id}/analytics/properties`. Sending only one leaves the other as it is. The stored data is not re-pulled by itself: refresh afterwards.","operationId":"update_analytics_connection_v1_brands__brand_id__analytics_connection_patch","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsConnectionUpdate"}}}},"responses":{"200":{"description":"Pick the property and the site","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsConnection"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:brands","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/analytics/pages":{"get":{"tags":["Analytics"],"summary":"Read one page's performance","description":"GA4 behaviour and Search Console numbers for a single page, with the queries that led to it. Pass the page `path` (e.g. `/blog/best-crm`); it matches any page whose path contains it. Use it to prove an article worked after publishing it. It asks Google live on every call, with nothing kept, so it is rate limited like the generation routes.\n\n`start_date` and `end_date` are `YYYY-MM-DD`; they default to the last 28 days up to today. Search Console lags two to three days: `data_through` says how far it is complete.","operationId":"get_page_performance_v1_brands__brand_id__analytics_pages_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"path","in":"query","required":true,"schema":{"type":"string","maxLength":2048,"description":"Page path, starting with `/`.","title":"Path"},"description":"Page path, starting with `/`."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"description":"First day of the window (YYYY-MM-DD).","title":"Start Date"},"description":"First day of the window (YYYY-MM-DD)."},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"description":"Last day of the window (YYYY-MM-DD).","title":"End Date"},"description":"Last day of the window (YYYY-MM-DD)."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Read one page's performance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PagePerformance"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:analytics","x-rankprompt-cost":{"request_units":2,"credits":0},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}}},"/v1/brands/{brand_id}/analytics/ai-traffic":{"get":{"tags":["Analytics"],"summary":"Read traffic the answer engines sent","description":"Visits GA4 attributes to the answer engines: sessions, users and page views per engine, the pages they land on, and the daily series. This is the other half of a visibility score: being named in an answer matters when it sends people.\n\n`start_date` and `end_date` are `YYYY-MM-DD`; they default to the last 28 days up to today.","operationId":"get_ai_traffic_v1_brands__brand_id__analytics_ai_traffic_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"description":"First day of the window (YYYY-MM-DD).","title":"Start Date"},"description":"First day of the window (YYYY-MM-DD)."},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"description":"Last day of the window (YYYY-MM-DD).","title":"End Date"},"description":"Last day of the window (YYYY-MM-DD)."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Read traffic the answer engines sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiTraffic"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:analytics","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/analytics/refreshes":{"post":{"tags":["Analytics"],"summary":"Pull the brand's Google data again","description":"Fetch GA4 and Search Console again for the window and store it. The reads serve what was last stored (except `analytics/pages`, and the queries and one query's history in `search-console/performance`, which ask Google live), so refresh when `last_sync_at` is null or old. Costs no credits. One refresh runs per brand at a time: `already_running` is true when another one was in flight, and its result lands in the same place. Send a fresh `Idempotency-Key` when you want a fresh pull: reusing one replays the stored answer.\n\n`start_date` and `end_date` are `YYYY-MM-DD`; they default to the last 28 days up to today.","operationId":"refresh_analytics_v1_brands__brand_id__analytics_refreshes_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/AnalyticsWindow"},{"type":"null"}],"title":"Body"}}}},"responses":{"202":{"description":"Pull the brand's Google data again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsRefresh"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:brands","x-rankprompt-cost":{"request_units":5,"credits":0},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}}},"/v1/brands/{brand_id}/analytics/properties":{"get":{"tags":["Analytics"],"summary":"List the Google properties on offer","description":"The GA4 properties and Search Console sites the linked Google account can read, plus the ones the brand currently points at. Pick with `PATCH /v1/brands/{brand_id}/analytics/connection`. Answers `400 google_not_connected` when no Google account is linked, and `400 google_connection_expired` when its token is dead; both carry a `connect_url`.","operationId":"list_google_properties_v1_brands__brand_id__analytics_properties_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned the Google properties on offer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoogleProperties"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:analytics","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/analytics/connection-links":{"post":{"tags":["Analytics"],"summary":"Mint a link that connects Google","description":"Return the link that connects this brand's Google. The user opens it signed in to Rank Prompt as an editor of the brand; the page takes them through Google's consent and stores the connection: nothing to send back here. Poll `GET /v1/brands/{brand_id}/analytics/connection` until `status` is `connected`, then pick the property and the site. The link asks for Google Analytics and Search Console and keeps whatever the connection already holds. Minting a link for a brand that is already connected is allowed and re-consents with the same Google account (`already_connected` says so); a different account is refused until Google is disconnected in the app.","operationId":"create_analytics_connection_link_v1_brands__brand_id__analytics_connection_links_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"201":{"description":"Mint a link that connects Google","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsConnectionLink"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:brands","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/search-console/sitemaps":{"get":{"tags":["Search Console"],"summary":"List submitted sitemaps","description":"Live sitemap-submission status pulled from Search Console for the brand's connected site, including per-sitemap error/warning counts and submitted-URL totals. The list is not cursor-paginated: it returns every submitted sitemap. `connected` is `false` (with an empty `data`) when no Search Console site is linked or readable. `site_url` reads another property the connected Google account can read (a blog on its own subdomain, say) instead of the brand's selected one.","operationId":"list_search_console_sitemaps_v1_brands__brand_id__search_console_sitemaps_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"site_url","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"description":"A Search Console property the connected account can read, exactly as Search Console names it (`https://blog.rankprompt.com/` or `sc-domain:rankprompt.com`). Default: the brand's selected one; one the account cannot read answers `connected: false`.","title":"Site Url"},"description":"A Search Console property the connected account can read, exactly as Search Console names it (`https://blog.rankprompt.com/` or `sc-domain:rankprompt.com`). Default: the brand's selected one; one the account cannot read answers `connected: false`."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned submitted sitemaps","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GscSitemapList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:analytics","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/search-console/url-inspection":{"get":{"tags":["Search Console"],"summary":"Inspect a URL in Search Console","description":"Live index status of a single page from the Search Console URL Inspection API: coverage and index verdicts, canonical selection, last crawl, and any detected rich results. Pass the page URL via the required `url` query parameter; it must belong to the connected GSC site. `connected` is `false` (with a `null` result) when no Search Console site is linked or the page could not be inspected. Single object.","operationId":"get_search_console_url_inspection_v1_brands__brand_id__search_console_url_inspection_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"url","in":"query","required":true,"schema":{"type":"string","description":"The page URL to inspect (must belong to the connected Search Console site).","title":"Url"},"description":"The page URL to inspect (must belong to the connected Search Console site)."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Inspect a URL in Search Console","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UrlInspection"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:analytics","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/search-console/performance":{"get":{"tags":["Search Console"],"summary":"Read Search Console performance","description":"What the brand's site earned in Google: clicks, impressions, CTR and average position, split by `dimension` (`query`, `page`, `country`, `device` or `date`). `totals` is the site-wide total for the window (`totals.key` says whether it is the site's own figure or the sum of the rows). CTR is a percentage. `dimension=query` reads every query Search Console exposes for the window live from Google (kept five minutes), most clicks first, paged with `limit` (1-1000, default 1000) and `offset`; `total` counts them all and `has_more` says another page follows. On a very large site the first read of a window can take a minute or more; calls for the same window share that read, and it finishes even when the caller gives up, so a retry a minute later is served from the kept copy. The other dimensions come whole from the stored snapshot: the top 1000 pages, 300 countries, every device, one row per day. Pass `query` with `dimension=date` to get one query's history day by day, read live from Google; `totals` stays the site's, not that query's.\n\nWith `dimension=query`: `search` keeps the queries holding that text (case and spacing ignored) and `order_by` (`query`, `clicks`, `impressions`, `ctr` or `position`) with `order_dir` (`asc` or `desc`, default `desc`) sorts them, ties broken by the query. `country` (the full English name, e.g. `United States`) reads `dimension=query` or `dimension=page` in that country only, live from Google and kept five minutes per window and country like the queries; `totals` stays the site's.\n\n`engine=bing` reads the same numbers from the brand's Bing Webmaster Tools site instead (connected in the app): `dimension` `query`, `page` or `date`, every query paged with `limit` and `offset`, every page whole; `query`, `search`, `order_by` and `country` are Google only. Bing is read again every six hours. Without a Bing site the call answers `integration_not_connected` with the page to connect it.\n\n`start_date` and `end_date` are `YYYY-MM-DD`; they default to the last 28 days up to today. Search Console lags two to three days: `data_through` says how far it is complete.","operationId":"get_search_performance_v1_brands__brand_id__search_console_performance_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"engine","in":"query","required":false,"schema":{"enum":["google","bing"],"type":"string","description":"`google` (Search Console, the default) or `bing` (Bing Webmaster Tools).","default":"google","title":"Engine"},"description":"`google` (Search Console, the default) or `bing` (Bing Webmaster Tools)."},{"name":"dimension","in":"query","required":false,"schema":{"enum":["query","page","country","device","date"],"type":"string","description":"What each row stands for.","default":"query","title":"Dimension"},"description":"What each row stands for."},{"name":"query","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}],"description":"With `dimension=date`, the query whose history to return.","title":"Query"},"description":"With `dimension=date`, the query whose history to return."},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"With `dimension=query`, only queries holding this text.","title":"Search"},"description":"With `dimension=query`, only queries holding this text."},{"name":"order_by","in":"query","required":false,"schema":{"anyOf":[{"enum":["query","clicks","impressions","ctr","position"],"type":"string"},{"type":"null"}],"description":"With `dimension=query`, the column to sort by.","title":"Order By"},"description":"With `dimension=query`, the column to sort by."},{"name":"order_dir","in":"query","required":false,"schema":{"enum":["asc","desc"],"type":"string","description":"Sort direction. Default `desc`.","default":"desc","title":"Order Dir"},"description":"Sort direction. Default `desc`."},{"name":"country","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"description":"With `dimension=query` or `page`, only searches from this country (full English name).","title":"Country"},"description":"With `dimension=query` or `page`, only searches from this country (full English name)."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"description":"First day of the window (YYYY-MM-DD).","title":"Start Date"},"description":"First day of the window (YYYY-MM-DD)."},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"description":"Last day of the window (YYYY-MM-DD).","title":"End Date"},"description":"Last day of the window (YYYY-MM-DD)."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"description":"With `dimension=query`, or a country, rows per page.","default":1000,"title":"Limit"},"description":"With `dimension=query`, or a country, rows per page."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"With `dimension=query`, or a country, rows to skip.","default":0,"title":"Offset"},"description":"With `dimension=query`, or a country, rows to skip."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Read Search Console performance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchPerformance"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:analytics","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/copilot-citations":{"get":{"tags":["Copilot Citations"],"summary":"List Copilot cited pages","description":"The pages Bing says Microsoft Copilot cited, from the Bing Webmaster Tools AI Performance export the brand uploaded in the app, most citations first. Each page carries `seen_by`: the engines whose answers in the brand's own completed reports cited the same page (the URL compared the way citations are stored), so the pages Copilot cites that the tracked engines do not stand out. `period_start` and `period_end` pick an uploaded period; without them the newest is read. Paged with `limit` and `cursor`. An empty list means no cited pages export was uploaded for the period.","operationId":"list_copilot_citations_v1_brands__brand_id__copilot_citations_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"period_start","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"description":"First day of an uploaded period (YYYY-MM-DD).","title":"Period Start"},"description":"First day of an uploaded period (YYYY-MM-DD)."},{"name":"period_end","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"description":"Last day of it (YYYY-MM-DD).","title":"Period End"},"description":"Last day of it (YYYY-MM-DD)."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Page size (default 20, max 100).","default":20,"title":"Limit"},"description":"Page size (default 20, max 100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Continuation token from a previous response's `next_cursor`.","title":"Cursor"},"description":"Continuation token from a previous response's `next_cursor`."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned Copilot cited pages","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CopilotCitationList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:analytics","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/openai-ads/performance":{"get":{"tags":["OpenAI Ads"],"summary":"Read OpenAI Ads performance","description":"Delivery and conversion metrics of the brand's OpenAI Ads for a window: impressions, clicks, spend, CTR, CPC, CPM, conversions, CPA, attributed sales and ROAS. `level` picks the scope (the whole `ad_account`, or one `campaign`, `ad_group` or `ad` named by `entity_id`) and `group_by` what each row stands for, at that level or below: the account grouped by `campaign` is one row per campaign. `granularity` `daily` or `monthly` splits each row by date. The attribution settings change every conversion number and are echoed back. OpenAI's report is kept up to an hour (15 minutes when split by date). Pages with `limit` and `cursor`.\n\nThe brand owner needs Pro or higher (`403 brand_plan_required`). A brand without an OpenAI Ads connection answers `400 integration_not_connected` with `details.connect_url`. Free: no credits. Money is in micros of the ad account's `currency` (1,000,000 is one unit). `start_date` and `end_date` are `YYYY-MM-DD`; they default to the last 28 days, the window is at most 365 days, and OpenAI reports up to yesterday (UTC). Ads are paid, labeled placements in ChatGPT, separate from the organic answers the visibility reports measure.","operationId":"get_openai_ads_performance_v1_brands__brand_id__openai_ads_performance_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"description":"First day of the window (YYYY-MM-DD).","title":"Start Date"},"description":"First day of the window (YYYY-MM-DD)."},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"description":"Last day of the window (YYYY-MM-DD).","title":"End Date"},"description":"Last day of the window (YYYY-MM-DD)."},{"name":"level","in":"query","required":false,"schema":{"enum":["ad_account","campaign","ad_group","ad"],"type":"string","description":"The scope read.","default":"ad_account","title":"Level"},"description":"The scope read."},{"name":"entity_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-]+$"},{"type":"null"}],"description":"The campaign, ad group or ad, with that `level`.","title":"Entity Id"},"description":"The campaign, ad group or ad, with that `level`."},{"name":"group_by","in":"query","required":false,"schema":{"anyOf":[{"enum":["ad_account","campaign","ad_group","ad"],"type":"string"},{"type":"null"}],"description":"What each row stands for, at `level` or below. Defaults to `level`.","title":"Group By"},"description":"What each row stands for, at `level` or below. Defaults to `level`."},{"name":"granularity","in":"query","required":false,"schema":{"enum":["none","daily","monthly"],"type":"string","description":"`none` totals the window.","default":"none","title":"Granularity"},"description":"`none` totals the window."},{"name":"attribution_window_days","in":"query","required":false,"schema":{"type":"integer","description":"Days after a click a conversion still counts: 7, 14 or 30.","enum":[7,14,30],"default":30,"title":"Attribution Window Days"},"description":"Days after a click a conversion still counts: 7, 14 or 30."},{"name":"view_through_attribution_window_days","in":"query","required":false,"schema":{"type":"integer","description":"Days after a view a conversion still counts: 0 leaves views out.","enum":[0,1],"default":1,"title":"View Through Attribution Window Days"},"description":"Days after a view a conversion still counts: 0 leaves views out."},{"name":"attribution_time_basis","in":"query","required":false,"schema":{"enum":["ad_event_time","conversion_time"],"type":"string","description":"`ad_event_time` files a conversion on the click or view's day, `conversion_time` on its own.","default":"ad_event_time","title":"Attribution Time Basis"},"description":"`ad_event_time` files a conversion on the click or view's day, `conversion_time` on its own."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":2000,"minimum":1,"description":"Rows per page.","default":200,"title":"Limit"},"description":"Rows per page."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"description":"`next_cursor` of the previous page, unchanged.","title":"Cursor"},"description":"`next_cursor` of the previous page, unchanged."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Read OpenAI Ads performance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsPerformance"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:ads","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/openai-ads/conversions":{"get":{"tags":["OpenAI Ads"],"summary":"Read OpenAI Ads attributed conversions","description":"Conversions OpenAI attributed to the brand's ads, from the pixel and the Conversions API: click-through, view-through, their total and the attributed sales, per `group_by` (`campaign` by default, `ad_group`, `ad`, or the whole `ad_account`). Without `entity_ids` every entity at that level is read. `include_events=true` nests each event's counts and value under its row (`event_names` keeps only some events there; the goal counts do not change). `granularity=daily` splits by day and `breakdown` by `country` or `device`. Every row comes back with `totals`; a report over OpenAI's 2,000 rows answers `400 validation_error`: ask for fewer days or entities.\n\nThe brand owner needs Pro or higher (`403 brand_plan_required`). A brand without an OpenAI Ads connection answers `400 integration_not_connected` with `details.connect_url`. Free: no credits. Money is in micros of the ad account's `currency` (1,000,000 is one unit). `start_date` and `end_date` are `YYYY-MM-DD`; they default to the last 28 days, the window is at most 365 days, and OpenAI reports up to yesterday (UTC). Ads are paid, labeled placements in ChatGPT, separate from the organic answers the visibility reports measure.","operationId":"get_openai_ads_conversions_v1_brands__brand_id__openai_ads_conversions_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"description":"First day of the window (YYYY-MM-DD).","title":"Start Date"},"description":"First day of the window (YYYY-MM-DD)."},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"description":"Last day of the window (YYYY-MM-DD).","title":"End Date"},"description":"Last day of the window (YYYY-MM-DD)."},{"name":"group_by","in":"query","required":false,"schema":{"enum":["ad_account","campaign","ad_group","ad"],"type":"string","description":"What each row stands for.","default":"campaign","title":"Group By"},"description":"What each row stands for."},{"name":"entity_ids","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":200},{"type":"null"}],"description":"Only these campaigns, ad groups or ads (repeat it); every one at `group_by` when omitted.","title":"Entity Ids"},"description":"Only these campaigns, ad groups or ads (repeat it); every one at `group_by` when omitted."},{"name":"granularity","in":"query","required":false,"schema":{"enum":["none","daily"],"type":"string","description":"`none` totals the window.","default":"none","title":"Granularity"},"description":"`none` totals the window."},{"name":"breakdown","in":"query","required":false,"schema":{"anyOf":[{"enum":["country","device"],"type":"string"},{"type":"null"}],"description":"Split rows by country or device.","title":"Breakdown"},"description":"Split rows by country or device."},{"name":"include_events","in":"query","required":false,"schema":{"type":"boolean","description":"Nest each event's attributed counts and value.","default":false,"title":"Include Events"},"description":"Nest each event's attributed counts and value."},{"name":"event_names","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":500},{"type":"null"}],"description":"With `include_events`, only these events (repeat it).","title":"Event Names"},"description":"With `include_events`, only these events (repeat it)."},{"name":"attribution_window_days","in":"query","required":false,"schema":{"type":"integer","description":"Days after a click a conversion still counts: 7, 14 or 30.","enum":[7,14,30],"default":30,"title":"Attribution Window Days"},"description":"Days after a click a conversion still counts: 7, 14 or 30."},{"name":"view_through_attribution_window_days","in":"query","required":false,"schema":{"type":"integer","description":"Days after a view a conversion still counts: 0 leaves views out.","enum":[0,1],"default":1,"title":"View Through Attribution Window Days"},"description":"Days after a view a conversion still counts: 0 leaves views out."},{"name":"attribution_time_basis","in":"query","required":false,"schema":{"enum":["ad_event_time","conversion_time"],"type":"string","description":"`ad_event_time` files a conversion on the click or view's day, `conversion_time` on its own.","default":"ad_event_time","title":"Attribution Time Basis"},"description":"`ad_event_time` files a conversion on the click or view's day, `conversion_time` on its own."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Read OpenAI Ads attributed conversions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsConversions"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:ads","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/openai-ads/campaigns":{"get":{"tags":["OpenAI Ads"],"summary":"List OpenAI Ads campaigns","description":"Every campaign of the brand's ad account with its status, daily or lifetime budget, bidding type and serving issues (why it is not delivering, or delivers less). Read from the copy the app keeps, at most five minutes old; `refresh=true` asks OpenAI first. `status` keeps one status. Not paginated.\n\nThe brand owner needs Pro or higher (`403 brand_plan_required`). A brand without an OpenAI Ads connection answers `400 integration_not_connected` with `details.connect_url`. Free: no credits. Money is in micros of the ad account's `currency` (1,000,000 is one unit). `start_date` and `end_date` are `YYYY-MM-DD`; they default to the last 28 days, the window is at most 365 days, and OpenAI reports up to yesterday (UTC). Ads are paid, labeled placements in ChatGPT, separate from the organic answers the visibility reports measure.","operationId":"list_openai_ads_campaigns_v1_brands__brand_id__openai_ads_campaigns_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"enum":["active","paused","archived","ended"],"type":"string"},{"type":"null"}],"description":"Only campaigns in this status.","title":"Status"},"description":"Only campaigns in this status."},{"name":"refresh","in":"query","required":false,"schema":{"type":"boolean","description":"Ask OpenAI instead of the kept copy.","default":false,"title":"Refresh"},"description":"Ask OpenAI instead of the kept copy."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned OpenAI Ads campaigns","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsCampaignList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:ads","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/shares":{"get":{"tags":["Shares"],"summary":"List the account's shares","description":"Every public link of the brands the key reaches in its account, of any kind: report, scheduled report, brand overview, brand audit, client report version and article review. Offset paginated: links and article reviews are two stores merged in the order asked for. Account level: a key restricted to one brand answers `403 forbidden`. Reading several brands at once is Agency Plus (`403 account_plan_required`); pass one `brand_id` on any plan.","operationId":"list_account_shares_v1_shares_get","parameters":[{"name":"brand_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":100},{"type":"null"}],"description":"Only these brands.","title":"Brand Id"},"description":"Only these brands."},{"name":"share_type","in":"query","required":false,"schema":{"anyOf":[{"enum":["report","scheduled","brand","brand_audit","portal","document","article_review"],"type":"string"},{"type":"null"}],"description":"Only this kind of link.","title":"Share Type"},"description":"Only this kind of link."},{"name":"order_by","in":"query","required":false,"schema":{"enum":["created_at","expires_at","view_count"],"type":"string","description":"Sort column.","default":"created_at","title":"Order By"},"description":"Sort column."},{"name":"order_dir","in":"query","required":false,"schema":{"enum":["asc","desc"],"type":"string","description":"Sort direction.","default":"desc","title":"Order Dir"},"description":"Sort direction."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Links per call (1-100, default 50).","default":50,"title":"Limit"},"description":"Links per call (1-100, default 50)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Links to skip.","default":0,"title":"Offset"},"description":"Links to skip."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned the account's shares","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountShareList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:brands","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/shares/{share_id}":{"delete":{"tags":["Shares"],"summary":"Revoke a share","description":"Revoke one link by id, on a brand the key's creator may edit; it stops opening at once. A link the key cannot reach answers `404`. Account level: a key restricted to one brand answers `403 forbidden`.","operationId":"revoke_account_share_v1_shares__share_id__delete","parameters":[{"name":"share_id","in":"path","required":true,"schema":{"type":"string","description":"Share id (UUID), from `GET /v1/shares`.","title":"Share Id"},"description":"Share id (UUID), from `GET /v1/shares`."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"204":{"description":"Revoked.","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:brands","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/me/webhooks":{"get":{"tags":["Webhooks"],"summary":"List account webhooks","description":"The account's endpoints for lead and prospect events, newest first, with their status. The account's owner only, on any plan; a key made in a team account or restricted to one brand answers `403 forbidden`.","operationId":"list_account_webhooks_v1_me_webhooks_get","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned account webhooks","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountWebhookList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:webhooks","x-rankprompt-cost":{"request_units":1,"credits":0}},"post":{"tags":["Webhooks"],"summary":"Create an account webhook","description":"An https endpoint for the account's lead and prospect events: each is posted there, signed, as it happens. The signing secret comes back once and is never stored in the clear. The account's owner only, on Agency Plus (`403 account_plan_required` otherwise; a trial holds 1 endpoint); a key made in a team account or restricted to one brand answers `403 forbidden`.","operationId":"create_account_webhook_v1_me_webhooks_post","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountWebhookCreate"}}}},"responses":{"201":{"description":"Created an account webhook","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountWebhookCreated"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:webhooks","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/me/webhooks/{webhook_id}":{"delete":{"tags":["Webhooks"],"summary":"Delete an account webhook","description":"Delete an endpoint and its delivery history; events stop reaching it. The account's owner only, on any plan: deleting what is yours is never behind a plan. A key made in a team account or restricted to one brand answers `403 forbidden`.","operationId":"delete_account_webhook_v1_me_webhooks__webhook_id__delete","parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","pattern":"^whk_[0-9a-f]{32}$","description":"`whk_` and 32 hex characters.","title":"Webhook Id"},"description":"`whk_` and 32 hex characters."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"204":{"description":"Deleted.","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:webhooks","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/agency/portfolio":{"get":{"tags":["Agency"],"summary":"Read the portfolio","description":"One row per brand of the account: visibility now and over the period, the trend, the engines its newest report asked and those naming it, reports, schedules, deliveries, pending reviews, open board cards and live shares. Account level and Agency Plus (`403 account_plan_required` otherwise): the owner or an all-brands member of the account; a key restricted to one brand answers `403 forbidden`.","operationId":"get_portfolio_v1_agency_portfolio_get","parameters":[{"name":"tags","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":50},{"type":"null"}],"description":"Only brands tagged with any of these.","title":"Tags"},"description":"Only brands tagged with any of these."},{"name":"max_brands","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"description":"Brands to read, the most active first.","default":1000,"title":"Max Brands"},"description":"Brands to read, the most active first."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Read the portfolio","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Portfolio"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:agency","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/agency/heatmap":{"get":{"tags":["Agency"],"summary":"Read the visibility heatmap","description":"Brand by engine: how often each brand is named and its average rank, over recent reports. It reads up to 100 brands unless `max_brands` asks for more (up to 1000). Account level and Agency Plus (`403 account_plan_required` otherwise): the owner or an all-brands member of the account; a key restricted to one brand answers `403 forbidden`.","operationId":"get_heatmap_v1_agency_heatmap_get","parameters":[{"name":"tags","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":50},{"type":"null"}],"description":"Only brands tagged with any of these.","title":"Tags"},"description":"Only brands tagged with any of these."},{"name":"brand_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":1000},{"type":"null"}],"description":"Only these brands.","title":"Brand Id"},"description":"Only these brands."},{"name":"max_brands","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"description":"Brands to read, 100 by default.","default":100,"title":"Max Brands"},"description":"Brands to read, 100 by default."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Read the visibility heatmap","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Heatmap"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:agency","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/agency/competitors":{"get":{"tags":["Agency"],"summary":"List the portfolio's competitors","description":"The competitors across the portfolio's recent reports, most mentioned first. Account level and Agency Plus (`403 account_plan_required` otherwise): the owner or an all-brands member of the account; a key restricted to one brand answers `403 forbidden`.","operationId":"list_portfolio_competitors_v1_agency_competitors_get","parameters":[{"name":"tags","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":50},{"type":"null"}],"description":"Only brands tagged with any of these.","title":"Tags"},"description":"Only brands tagged with any of these."},{"name":"brand_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":1000},{"type":"null"}],"description":"Only these brands.","title":"Brand Id"},"description":"Only these brands."},{"name":"top_n","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"description":"Competitors to return.","default":25,"title":"Top N"},"description":"Competitors to return."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned the portfolio's competitors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortfolioCompetitorList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:agency","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/agency/tasks":{"get":{"tags":["Agency"],"summary":"List the portfolio's tasks","description":"Tasks across every brand of the account, sorted as the Agency tasks page sorts them: by `order_by` (`brand_name`, `priority` by rank so `asc` reads high, medium, low, `created_at` or `due_date`), ties and an omitted `order_by` going by due date (undated last), then newest first. Without `status` the list holds accepted work; ask for `suggested` or `dismissed` to read those. Offset paginated. Account level and Agency Plus (`403 account_plan_required` otherwise): the owner or an all-brands member of the account; a key restricted to one brand answers `403 forbidden`.","operationId":"list_agency_tasks_v1_agency_tasks_get","parameters":[{"name":"tags","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":50},{"type":"null"}],"description":"Only brands tagged with any of these.","title":"Tags"},"description":"Only brands tagged with any of these."},{"name":"brand_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":1000},{"type":"null"}],"description":"Only these brands.","title":"Brand Id"},"description":"Only these brands."},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"enum":["suggested","backlog","in_progress","review","approved","done","dismissed"],"type":"string"}},{"type":"null"}],"description":"Any of these stages.","title":"Status"},"description":"Any of these stages."},{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"description":"One category, e.g. `CONTENT`.","title":"Category"},"description":"One category, e.g. `CONTENT`."},{"name":"priority","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"description":"`high`, `medium` or `low`.","title":"Priority"},"description":"`high`, `medium` or `low`."},{"name":"source_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"description":"What generated the task.","title":"Source Type"},"description":"What generated the task."},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Words in the title.","title":"Search"},"description":"Words in the title."},{"name":"has_article","in":"query","required":false,"schema":{"type":"boolean","description":"Only tasks with a linked article.","default":false,"title":"Has Article"},"description":"Only tasks with a linked article."},{"name":"show_archived","in":"query","required":false,"schema":{"type":"boolean","description":"Include archived tasks.","default":false,"title":"Show Archived"},"description":"Include archived tasks."},{"name":"order_by","in":"query","required":false,"schema":{"anyOf":[{"enum":["brand_name","priority","created_at","due_date"],"type":"string"},{"type":"null"}],"description":"Sort column; omitted, due date first.","title":"Order By"},"description":"Sort column; omitted, due date first."},{"name":"order_dir","in":"query","required":false,"schema":{"enum":["asc","desc"],"type":"string","description":"Direction of `order_by`, default `asc`.","default":"asc","title":"Order Dir"},"description":"Direction of `order_by`, default `asc`."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"description":"Tasks per call.","default":50,"title":"Limit"},"description":"Tasks per call."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Tasks to skip.","default":0,"title":"Offset"},"description":"Tasks to skip."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned the portfolio's tasks","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyTaskList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:agency","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/agency/tasks/summary":{"get":{"tags":["Agency"],"summary":"Count the portfolio's tasks","description":"Task counts across the portfolio by status and priority, archived tasks left out. `by_priority` counts accepted work, or the tasks of `status` when given: `status=backlog&status=in_progress&status=review` answers how many open tasks are high priority. Account level and Agency Plus (`403 account_plan_required` otherwise): the owner or an all-brands member of the account; a key restricted to one brand answers `403 forbidden`.","operationId":"get_agency_task_summary_v1_agency_tasks_summary_get","parameters":[{"name":"tags","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":50},{"type":"null"}],"description":"Only brands tagged with any of these.","title":"Tags"},"description":"Only brands tagged with any of these."},{"name":"brand_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":1000},{"type":"null"}],"description":"Only these brands.","title":"Brand Id"},"description":"Only these brands."},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"enum":["suggested","backlog","in_progress","review","approved","done","dismissed"],"type":"string"}},{"type":"null"}],"description":"Count the priorities of these stages only.","title":"Status"},"description":"Count the priorities of these stages only."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Count the portfolio's tasks","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyTaskSummary"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:agency","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/agency/reviews":{"get":{"tags":["Agency"],"summary":"List pending article reviews","description":"Article reviews waiting on someone across the portfolio, oldest first. Offset paginated. Account level and Agency Plus (`403 account_plan_required` otherwise): the owner or an all-brands member of the account; a key restricted to one brand answers `403 forbidden`.","operationId":"list_agency_reviews_v1_agency_reviews_get","parameters":[{"name":"tags","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":50},{"type":"null"}],"description":"Only brands tagged with any of these.","title":"Tags"},"description":"Only brands tagged with any of these."},{"name":"brand_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":1000},{"type":"null"}],"description":"Only these brands.","title":"Brand Id"},"description":"Only these brands."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"description":"Reviews per call.","default":50,"title":"Limit"},"description":"Reviews per call."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Reviews to skip.","default":0,"title":"Offset"},"description":"Reviews to skip."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned pending article reviews","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyReviewList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:agency","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/agency/prospect-lists":{"get":{"tags":["Agency"],"summary":"List prospect lists","description":"The account's prospect lists with how many prospects each holds, newest first. The list marked `website_leads` holds the site widget's leads. Offset paginated. Account level, on any plan: the owner or an all-brands member of the account; a key restricted to one brand answers `403 forbidden`.","operationId":"list_prospect_lists_v1_agency_prospect_lists_get","parameters":[{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Words in the list's name.","title":"Search"},"description":"Words in the list's name."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"description":"Lists per call.","default":50,"title":"Limit"},"description":"Lists per call."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Lists to skip.","default":0,"title":"Offset"},"description":"Lists to skip."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned prospect lists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProspectListList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:agency","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/agency/prospect-lists/{list_id}":{"get":{"tags":["Agency"],"summary":"Retrieve a prospect list","description":"A prospect list and a page of its prospects, newest first or by `sort`. `sort=opportunity_score` puts the prospects worth calling first on top. Offset paginated. Account level, on any plan: the owner or an all-brands member of the account; a key restricted to one brand answers `403 forbidden`.","operationId":"get_prospect_list_v1_agency_prospect_lists__list_id__get","parameters":[{"name":"list_id","in":"path","required":true,"schema":{"type":"string","description":"Prospect list id (UUID).","title":"List Id"},"description":"Prospect list id (UUID)."},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Company, website, contact name or email.","title":"Search"},"description":"Company, website, contact name or email."},{"name":"sort","in":"query","required":false,"schema":{"enum":["created_at","company_name","rating","opportunity_score"],"type":"string","description":"Order of the prospects, descending.","default":"created_at","title":"Sort"},"description":"Order of the prospects, descending."},{"name":"min_score","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":100,"minimum":0},{"type":"null"}],"description":"Only prospects scoring at least this.","title":"Min Score"},"description":"Only prospects scoring at least this."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Prospects per call.","default":50,"title":"Limit"},"description":"Prospects per call."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Prospects to skip.","default":0,"title":"Offset"},"description":"Prospects to skip."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned a prospect list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProspectListDetail"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:agency","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/agency/prospects/funnel":{"get":{"tags":["Agency"],"summary":"Read the prospect pipeline","description":"How many prospects sit at each stage across every list, and split into the ones searched for (`outbound`) and the site widget's leads (`widget`). Account level, on any plan: the owner or an all-brands member of the account; a key restricted to one brand answers `403 forbidden`.","operationId":"get_prospect_funnel_v1_agency_prospects_funnel_get","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Read the prospect pipeline","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProspectFunnel"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:agency","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/agency/prospecting-overview":{"get":{"tags":["Agency"],"summary":"Read what waits in prospecting","description":"What waits on the agency across every list, counting only the prospects it goes after (outbound and from the clients' reports): prospects who opened their report and have not replied, pitches to review, approved pitches not sent, pitches with no contact email, and the reports, pitches and sends that failed, each with how many lists hold them and the list holding the most. The website's widget leads are counted apart in `leads`. Also the prospects' lost deals by reason and their campaign emails of the last 30 days, sent, opened and replied, by day. Who opened their report: `GET /v1/agency/prospect-report-views`. Account level, on any plan: the owner or an all-brands member of the account; a key restricted to one brand answers `403 forbidden`.","operationId":"get_prospecting_overview_v1_agency_prospecting_overview_get","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Read what waits in prospecting","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProspectingOverview"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:agency","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/agency/prospect-report-views":{"get":{"tags":["Agency"],"summary":"List who opened their report","description":"Who opened the report they were sent and waits on the agency, newest open first: `audience=prospects` are prospects sent outreach with no reply yet (the moment to call), `audience=leads` the website's widget leads not contacted, won or lost yet. Cursor paginated. Account level, on any plan: the owner or an all-brands member of the account; a key restricted to one brand answers `403 forbidden`.","operationId":"list_prospect_report_views_v1_agency_prospect_report_views_get","parameters":[{"name":"audience","in":"query","required":false,"schema":{"enum":["leads","prospects"],"type":"string","description":"`prospects` sent outreach, or the website's widget `leads`.","default":"prospects","title":"Audience"},"description":"`prospects` sent outreach, or the website's widget `leads`."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Page size (default 20, max 100).","default":20,"title":"Limit"},"description":"Page size (default 20, max 100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Continuation token from a previous response's `next_cursor`.","title":"Cursor"},"description":"Continuation token from a previous response's `next_cursor`."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned who opened their report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProspectReportViewList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:agency","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/agency/prospect-searches":{"post":{"tags":["Agency"],"summary":"Search for prospects","description":"Find companies by sector and place through Google Maps and AI enrichment. Costs 5 credits, charged to the account. The results are kept as the account's latest search; save the ones worth keeping into a list in the app. Needs Agency Plus and write access to the account; a key restricted to one brand answers `403 forbidden`.","operationId":"search_prospects_v1_agency_prospect_searches_post","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProspectSearchRequest"}}}},"responses":{"201":{"description":"Search for prospects","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProspectSearch"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"402":{"description":"Not enough credits to complete this operation","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"insufficient_credits","message":"Not enough credits to complete this operation"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:prospects","x-rankprompt-cost":{"request_units":5,"credits":5},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}}},"/v1/agency/prospect-lists/{list_id}/prospects":{"post":{"tags":["Agency"],"summary":"Save prospects into a list","description":"Save businesses into a prospect list: candidates of a search, suggestions from the clients' reports, or your own. One already in this list is never saved twice and a client of the account is left out unless `include_duplicates`; the answer says how many were left out and why. The Google data of what your latest search found is included in that search; anything else is scored from shared data, free. Needs Agency Plus and write access to the account; a key restricted to one brand answers `403 forbidden`.","operationId":"save_prospects_v1_agency_prospect_lists__list_id__prospects_post","parameters":[{"name":"list_id","in":"path","required":true,"schema":{"type":"string","description":"Prospect list id (UUID).","title":"List Id"},"description":"Prospect list id (UUID)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProspectSaveRequest"}}}},"responses":{"201":{"description":"Save prospects into a list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProspectSaveResult"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:prospects","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/agency/prospects/{prospect_id}/reports":{"post":{"tags":["Agency"],"summary":"Run a prospect's AI visibility report","description":"Build the prospect's report (its brand, the prompts) and queue its run. Engines and prompt count come from the body, then the list's report setup, then the account's default; a list that fixes its prompts asks exactly those. A prompt costs `ceil(engines / 3)` credits (`?dry_run=true` shows the total), charged when the run starts and refunded for what does not answer. Poll `GET /v1/jobs/{job_id}`, then read `GET /v1/reports/{report_id}`. Needs Agency Plus; a key restricted to one brand answers `403 forbidden`.","operationId":"run_prospect_report_v1_agency_prospects__prospect_id__reports_post","parameters":[{"name":"prospect_id","in":"path","required":true,"schema":{"type":"string","description":"Prospect id (UUID).","title":"Prospect Id"},"description":"Prospect id (UUID)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProspectReportRequest"}}}},"responses":{"202":{"description":"The report is built and its run queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProspectReportDispatched"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"402":{"description":"Not enough credits to complete this operation","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"insufficient_credits","message":"Not enough credits to complete this operation"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:prospects","x-rankprompt-cost":{"request_units":5,"credits":0},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}}},"/v1/agency/prospects/{prospect_id}/contact-lookups":{"post":{"tags":["Agency"],"summary":"Find a prospect's contact","description":"Look up a person to write to on the prospect's own website domain and save their email, name and title on the prospect. 1 credit, charged only when someone is found. A search already looks up its ten best candidates; this is for the rest. Answers `409 conflict` when the prospect has an email or a lookup is running, and `400 validation_error` when its website is missing or a page on a shared platform. Needs Agency Plus.","operationId":"find_prospect_contact_v1_agency_prospects__prospect_id__contact_lookups_post","parameters":[{"name":"prospect_id","in":"path","required":true,"schema":{"type":"string","description":"Prospect id (UUID).","title":"Prospect Id"},"description":"Prospect id (UUID)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"201":{"description":"Find a prospect's contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProspectContactLookup"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"402":{"description":"Not enough credits to complete this operation","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"insufficient_credits","message":"Not enough credits to complete this operation"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:prospects","x-rankprompt-cost":{"request_units":3,"credits":1}}},"/v1/agency/prospects/{prospect_id}/profile-audits":{"post":{"tags":["Agency"],"summary":"Audit a prospect's Business Profile","description":"Audit the prospect's Google Business Profile from what Google shows anyone: its profile, reviews, map, website and its Trustpilot and Tripadvisor ratings. The business is the prospect's Google place, else its name at its address, else in its city (its own, else its list's), the first of Google's top 3 results that is the prospect (`business.matched_by`); one with none answers `400 validation_error` (`profile_auditable` says it first). What only the owner sees reads as `not_measurable` with reason `needs_access`, so the score is over what could be read. 2 credits a run, reserved before the read and refunded if Google has no such business or the read fails. One at a time per prospect (`409 conflict` while one runs). It runs in the background for a few minutes (`202`): poll `GET /v1/jobs/{job_id}`, then read the audit with `GET .../profile-audits/{audit_id}`. Its score moves the prospect's `opportunity_score` and its worst failures go into the pitch. Account level and Agency Plus (`403 account_plan_required` otherwise): the owner or an all-brands member of the account; a key restricted to one brand answers `403 forbidden`.","operationId":"run_prospect_profile_audit_v1_agency_prospects__prospect_id__profile_audits_post","parameters":[{"name":"prospect_id","in":"path","required":true,"schema":{"type":"string","description":"Prospect id (UUID).","title":"Prospect Id"},"description":"Prospect id (UUID)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"202":{"description":"The audit is queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProspectProfileAuditDispatched"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"402":{"description":"Not enough credits to complete this operation","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"insufficient_credits","message":"Not enough credits to complete this operation"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:prospects","x-rankprompt-cost":{"request_units":3,"credits":2},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}},"get":{"tags":["Agency"],"summary":"List a prospect's Business Profile audits","description":"A page of the prospect's profile audits, newest first, each with its score, coverage and the business read. Follow `next_cursor` while `has_more`. Account level, on any plan: the owner or an all-brands member of the account; a key restricted to one brand answers `403 forbidden`.","operationId":"list_prospect_profile_audits_v1_agency_prospects__prospect_id__profile_audits_get","parameters":[{"name":"prospect_id","in":"path","required":true,"schema":{"type":"string","description":"Prospect id (UUID).","title":"Prospect Id"},"description":"Prospect id (UUID)."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Page size (default 20, max 100).","default":20,"title":"Limit"},"description":"Page size (default 20, max 100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Continuation token from a previous response's `next_cursor`.","title":"Cursor"},"description":"Continuation token from a previous response's `next_cursor`."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned a prospect's Business Profile audits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProspectProfileAuditList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:agency","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/agency/prospects/{prospect_id}/profile-audits/{audit_id}":{"get":{"tags":["Agency"],"summary":"Retrieve a prospect's Business Profile audit","description":"One profile audit with every check, what it found and the business read. Account level, on any plan: the owner or an all-brands member of the account; a key restricted to one brand answers `403 forbidden`.","operationId":"get_prospect_profile_audit_v1_agency_prospects__prospect_id__profile_audits__audit_id__get","parameters":[{"name":"prospect_id","in":"path","required":true,"schema":{"type":"string","description":"Prospect id (UUID).","title":"Prospect Id"},"description":"Prospect id (UUID)."},{"name":"audit_id","in":"path","required":true,"schema":{"type":"string","description":"The audit's id, from `GET .../profile-audits`.","title":"Audit Id"},"description":"The audit's id, from `GET .../profile-audits`."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned a prospect's Business Profile audit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProspectProfileAudit"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:agency","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/agency/prospects/{prospect_id}/pitch":{"post":{"tags":["Agency"],"summary":"Write a prospect's pitch","description":"Write a cold pitch email from the prospect's finished report (the engines that ran, its score, the competitor ahead of it, its Google footprint, the worst failures of its newest Business Profile audit and your scheduling link) and save it on the prospect, where the cadence sends it first. 1 credit, every time. Needs a finished report: answers `409 conflict` while it still runs. Needs Agency Plus.","operationId":"write_prospect_pitch_v1_agency_prospects__prospect_id__pitch_post","parameters":[{"name":"prospect_id","in":"path","required":true,"schema":{"type":"string","description":"Prospect id (UUID).","title":"Prospect Id"},"description":"Prospect id (UUID)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"201":{"description":"Write a prospect's pitch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProspectPitch"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"402":{"description":"Not enough credits to complete this operation","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"insufficient_credits","message":"Not enough credits to complete this operation"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:prospects","x-rankprompt-cost":{"request_units":3,"credits":1},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}}},"/v1/agency/prospect-lists/{list_id}/pipeline":{"get":{"tags":["Agency"],"summary":"Read a prospect list's outreach pipeline","description":"A list by outreach stage: `found`, `report` (its report runs, or is done with no pitch yet), `drafted` (a pitch waits for approval), `approved`, `sent` and `closed`, each stage's count and its best prospects by opportunity score, with what is queued and how many have no address. Account level, on any plan: the owner or an all-brands member of the account; a key restricted to one brand answers `403 forbidden`.","operationId":"get_prospect_pipeline_v1_agency_prospect_lists__list_id__pipeline_get","parameters":[{"name":"list_id","in":"path","required":true,"schema":{"type":"string","description":"Prospect list id (UUID).","title":"List Id"},"description":"Prospect list id (UUID)."},{"name":"per_stage","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Prospects shown per stage.","default":25,"title":"Per Stage"},"description":"Prospects shown per stage."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Read a prospect list's outreach pipeline","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProspectPipeline"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:agency","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/agency/prospect-lists/{list_id}/pipeline-runs":{"post":{"tags":["Agency"],"summary":"Move prospects one stage on","description":"Move up to 100 prospects of a list one stage on, each in the background: `report` builds and runs their reports (a prompt costs `ceil(engines / 3)` credits, plus 1 for the pitch with `then_pitch`), `pitch` writes their pitches (1 credit each; one with no report gets a quick pitch from what the search found), `approve` approves drafted pitches that are ready, `send` starts the outreach of approved ones, and `audit` audits the Business Profiles of those that can be audited (2 credits each). What the reports, pitches and audits would charge is checked against the balance first and `?dry_run=true` shows it. A send goes only to an approved prospect that is ready (`not_ready_reasons` empty), once per address across the account, from a connected mailbox within its daily limit, and needs the business mailing address (`400 sender_address_missing`, `400 mailbox_missing`). The answer says what started and what was left out and why; read the list or its pipeline to follow it. Needs Agency Plus; a key restricted to one brand answers `403 forbidden`.","operationId":"run_prospect_pipeline_v1_agency_prospect_lists__list_id__pipeline_runs_post","parameters":[{"name":"list_id","in":"path","required":true,"schema":{"type":"string","description":"Prospect list id (UUID).","title":"List Id"},"description":"Prospect list id (UUID)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProspectPipelineRunRequest"}}}},"responses":{"202":{"description":"The steps are queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProspectPipelineRun"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"402":{"description":"Not enough credits to complete this operation","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"insufficient_credits","message":"Not enough credits to complete this operation"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:prospects","x-rankprompt-cost":{"request_units":5,"credits":0},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}}},"/v1/agency/prospects/{prospect_id}/outreach-preview":{"get":{"tags":["Agency"],"summary":"Preview a prospect's outreach","description":"The prospect's outreach as it would go out: each email with its real values, each variable filled, on its fallback (`{{first_name|there}}`) or missing, the sentences left out for a missing value, and whether it is ready to send. Free. Account level, on any plan: the owner or an all-brands member of the account; a key restricted to one brand answers `403 forbidden`.","operationId":"preview_prospect_outreach_v1_agency_prospects__prospect_id__outreach_preview_get","parameters":[{"name":"prospect_id","in":"path","required":true,"schema":{"type":"string","description":"Prospect id (UUID).","title":"Prospect Id"},"description":"Prospect id (UUID)."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Preview a prospect's outreach","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProspectOutreachPreview"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:agency","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/agency/prospects/{prospect_id}":{"patch":{"tags":["Agency"],"summary":"Update a prospect","description":"Edit a prospect's details or move it: `won` turns its brand into a client brand and can invite the client to a client seat, create three kickoff tasks and schedule a weekly report with the same prompts and engines (each step on its own: the answer says which ran), and a second `won` changes nothing; `lost` keeps a reason and a day to look again; `new` reopens a lost deal, back to `ready` when its report is done (`generating` while it runs). Free. Needs Agency Plus; a key restricted to one brand answers `403 forbidden`.","operationId":"update_prospect_v1_agency_prospects__prospect_id__patch","parameters":[{"name":"prospect_id","in":"path","required":true,"schema":{"type":"string","description":"Prospect id (UUID).","title":"Prospect Id"},"description":"Prospect id (UUID)."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProspectUpdateRequest"}}}},"responses":{"200":{"description":"Updated a prospect","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProspectUpdated"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:prospects","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/agency/prospect-suggestions":{"get":{"tags":["Agency"],"summary":"List prospects suggested by the clients' reports","description":"Businesses the engines name as competitors of the account's clients, or cite in their answers, one row per domain with how often and for which clients. The best prospects come first: businesses the engines cite, then named competitors that compete with no client, then the direct competitors of a client. Never the account's own client sites, a prospect brand's report or a dismissed domain. An aggregate read: offset paginated, ordered by that group, then mentions, then domain. Save the ones worth pitching with `POST /v1/agency/prospect-lists/{list_id}/prospects`. Account level and Agency Plus (`403 account_plan_required` otherwise): the owner or an all-brands member of the account; a key restricted to one brand answers `403 forbidden`.","operationId":"list_prospect_suggestions_v1_agency_prospect_suggestions_get","parameters":[{"name":"tags","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":50},{"type":"null"}],"description":"Only brands tagged with any of these.","title":"Tags"},"description":"Only brands tagged with any of these."},{"name":"brand_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":1000},{"type":"null"}],"description":"Only these brands.","title":"Brand Id"},"description":"Only these brands."},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Words in the business name or domain.","title":"Q"},"description":"Words in the business name or domain."},{"name":"source","in":"query","required":false,"schema":{"anyOf":[{"enum":["competitor","citation"],"type":"string"},{"type":"null"}],"description":"Only businesses named as competitors, or only businesses cited in answers.","title":"Source"},"description":"Only businesses named as competitors, or only businesses cited in answers."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Suggestions per call.","default":25,"title":"Limit"},"description":"Suggestions per call."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Suggestions to skip.","default":0,"title":"Offset"},"description":"Suggestions to skip."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned prospects suggested by the clients' reports","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProspectSuggestionList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:agency","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/agency/saved-prospect-searches":{"get":{"tags":["Agency"],"summary":"List saved prospect searches","description":"The account's searches that run again every week, with what the active ones spend together (5 credits a run each). Account level, on any plan: the owner or an all-brands member of the account; a key restricted to one brand answers `403 forbidden`.","operationId":"list_saved_prospect_searches_v1_agency_saved_prospect_searches_get","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned saved prospect searches","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedProspectSearchList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:agency","x-rankprompt-cost":{"request_units":1,"credits":0}},"post":{"tags":["Agency"],"summary":"Save a prospect search to run every week","description":"Run this search now and again every week: 5 credits a run, the probe of AI answers and the Google data of what it saves included. Each run keeps only the businesses the account did not have, saved into `target_list_id` or kept on the run for review. A run without balance pauses the search. At most 10 run per account, 2 during a trial (`403 brand_plan_required` past it, with `details.reason` `trial_limit`). `?dry_run=true` shows the first run's cost. Needs Agency Plus.","operationId":"create_saved_prospect_search_v1_agency_saved_prospect_searches_post","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedProspectSearchCreate"}}}},"responses":{"201":{"description":"Save a prospect search to run every week","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedProspectSearch"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"402":{"description":"Not enough credits to complete this operation","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"insufficient_credits","message":"Not enough credits to complete this operation"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:prospects","x-rankprompt-cost":{"request_units":2,"credits":5}}},"/v1/agency/saved-prospect-searches/{search_id}":{"patch":{"tags":["Agency"],"summary":"Pause, resume or retarget a saved prospect search","description":"Pause a weekly search, change the list its finds go to, or resume it (it runs again now, within the same caps as creating one). Account level and Agency Plus (`403 account_plan_required` otherwise): the owner or an all-brands member of the account; a key restricted to one brand answers `403 forbidden`.","operationId":"update_saved_prospect_search_v1_agency_saved_prospect_searches__search_id__patch","parameters":[{"name":"search_id","in":"path","required":true,"schema":{"type":"string","description":"Saved search id (UUID).","title":"Search Id"},"description":"Saved search id (UUID)."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedProspectSearchUpdate"}}}},"responses":{"200":{"description":"Pause, resume or retarget a saved prospect search","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedProspectSearch"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:prospects","x-rankprompt-cost":{"request_units":1,"credits":0}},"delete":{"tags":["Agency"],"summary":"Delete a saved prospect search","description":"Delete a weekly search and its runs. Deleting what is yours is never behind a plan.","operationId":"delete_saved_prospect_search_v1_agency_saved_prospect_searches__search_id__delete","parameters":[{"name":"search_id","in":"path","required":true,"schema":{"type":"string","description":"Saved search id (UUID).","title":"Search Id"},"description":"Saved search id (UUID)."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"204":{"description":"Deleted a saved prospect search","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:prospects","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/agency/saved-prospect-searches/{search_id}/runs":{"get":{"tags":["Agency"],"summary":"List a saved prospect search's runs","description":"A page of one saved search's weekly runs, newest first, each with what it found, what was new and what it charged, and the new businesses of a run without a target list. Offset paginated. Account level, on any plan: the owner or an all-brands member of the account; a key restricted to one brand answers `403 forbidden`.","operationId":"list_saved_prospect_search_runs_v1_agency_saved_prospect_searches__search_id__runs_get","parameters":[{"name":"search_id","in":"path","required":true,"schema":{"type":"string","description":"Saved search id (UUID).","title":"Search Id"},"description":"Saved search id (UUID)."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Runs per call.","default":20,"title":"Limit"},"description":"Runs per call."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Runs to skip.","default":0,"title":"Offset"},"description":"Runs to skip."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned a saved prospect search's runs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedProspectSearchRunList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:agency","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/agency/undated-articles":{"get":{"tags":["Agency"],"summary":"List the undated articles across the portfolio","description":"The undated articles of every brand asked for in one list, each with its `brand_id`: drafts and articles ready for review with no `planned_publish_at`, no publish queued and no pull request waiting, newest change first. Without `brand_id` it reads every brand of the account. A brand the key cannot read answers `404 not_found`. Page with `limit` and `offset`. Account level and Agency Plus (`403 account_plan_required` otherwise): the owner or an all-brands member of the account; a key restricted to one brand answers `403 forbidden`.","operationId":"list_portfolio_undated_articles_v1_agency_undated_articles_get","parameters":[{"name":"brand_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":500},{"type":"null"}],"description":"Only these brands; every brand without any.","title":"Brand Id"},"description":"Only these brands; every brand without any."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Articles per page.","default":20,"title":"Limit"},"description":"Articles per page."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Articles to skip.","default":0,"title":"Offset"},"description":"Articles to skip."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned the undated articles across the portfolio","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UndatedArticleList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:agency","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/analytics/summary":{"get":{"tags":["Analytics"],"summary":"Analytics summary","description":"The last 28 days of the brand's Google data in one read: top Search Console queries, pages and countries, top GA4 pages and the visits the answer engines sent. Read from the stored copy, refreshed when stale. A brand without Google connected answers `400 google_not_connected` with the page to connect it.","operationId":"get_analytics_summary_v1_brands__brand_id__analytics_summary_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Analytics summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsSummary"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:analytics","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/client-report-versions/{version_id}/shares":{"post":{"tags":["Client reports"],"summary":"Share a client report version","description":"A public link to one published version of the brand's client report, white-labeled, that the client opens without an account. Sharing the same version again refreshes its link. Needs edit access to the brand.","operationId":"share_client_report_version_v1_brands__brand_id__client_report_versions__version_id__shares_post","parameters":[{"name":"version_id","in":"path","required":true,"schema":{"type":"string","description":"Published version id (UUID).","title":"Version Id"},"description":"Published version id (UUID)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientReportShareCreate"}}}},"responses":{"201":{"description":"Share a client report version","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientReportShare"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:client-reports","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/client-reports":{"get":{"tags":["Client reports"],"summary":"List client reports","description":"The account's client reports, the branded documents an agency builds and sends (not visibility runs), with the version each points at. One `brand_id` reads on any plan; several or none at once is Agency Plus (`403 account_plan_required`). Offset paginated. Account level: a key restricted to one brand answers `403 forbidden`.","operationId":"list_client_reports_v1_client_reports_get","parameters":[{"name":"brand_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":100},{"type":"null"}],"description":"Only these brands.","title":"Brand Id"},"description":"Only these brands."},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"enum":["draft","published","archived","review"],"type":"string"},{"type":"null"}],"description":"Only this status; `review` is a version a schedule holds for review.","title":"Status"},"description":"Only this status; `review` is a version a schedule holds for review."},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Words in the title.","title":"Search"},"description":"Words in the title."},{"name":"order_by","in":"query","required":false,"schema":{"enum":["updated_at","title","template_key","brand_name","published_at"],"type":"string","description":"Sort column.","default":"updated_at","title":"Order By"},"description":"Sort column."},{"name":"order_dir","in":"query","required":false,"schema":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"description":"Sort direction.","title":"Order Dir"},"description":"Sort direction."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Reports per call.","default":25,"title":"Limit"},"description":"Reports per call."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Reports to skip.","default":0,"title":"Offset"},"description":"Reports to skip."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned client reports","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientReportList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:client-reports","x-rankprompt-cost":{"request_units":1,"credits":0}},"post":{"tags":["Client reports"],"summary":"Create a client report","description":"Start a client report for a brand from a house template, one of the account's templates, the account's default, or blank. Needs edit access to the brand. Account level: a key restricted to one brand answers `403 forbidden`.","operationId":"create_client_report_v1_client_reports_post","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientReportCreate"}}}},"responses":{"201":{"description":"Created a client report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientReport"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:client-reports","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/client-reports/versions/{version_id}/deliveries":{"post":{"tags":["Client reports"],"summary":"Send a held client report","description":"Email the client the version its schedule held for review, now. A version already sent, or one that goes out on its own, answers `409`; a PDF still being made answers `409` too, retry in a minute. Needs the account on Agency (`403 account_plan_required`); a trial sends 20 client report emails in all. Account level: a key restricted to one brand answers `403 forbidden`.","operationId":"send_client_report_v1_client_reports_versions__version_id__deliveries_post","parameters":[{"name":"version_id","in":"path","required":true,"schema":{"type":"string","description":"Published version id (UUID).","title":"Version Id"},"description":"Published version id (UUID)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"201":{"description":"Send a held client report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientReportDelivery"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:client-reports","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/client-reports/{document_id}":{"get":{"tags":["Client reports"],"summary":"Retrieve a client report","description":"One client report as it stands, draft included, with its sheets and sentences. Account level: a key restricted to one brand answers `403 forbidden`.","operationId":"get_client_report_v1_client_reports__document_id__get","parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","description":"Client report id (UUID).","title":"Document Id"},"description":"Client report id (UUID)."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned a client report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientReport"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:client-reports","x-rankprompt-cost":{"request_units":1,"credits":0}},"patch":{"tags":["Client reports"],"summary":"Edit a client report","description":"Rename the report and apply edit operations in order, all or none: add, remove, move, toggle and configure blocks, move and remove sheets, write a block's sentence. An operation the report cannot take answers `400` naming it, and nothing is written. A report edited elsewhere since it was read answers `409`; read it and send the edits again. Account level: a key restricted to one brand answers `403 forbidden`.","operationId":"edit_client_report_v1_client_reports__document_id__patch","parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","description":"Client report id (UUID).","title":"Document Id"},"description":"Client report id (UUID)."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientReportUpdate"}}}},"responses":{"200":{"description":"Edit a client report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientReportEdited"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:client-reports","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/client-reports/{document_id}/facts":{"get":{"tags":["Client reports"],"summary":"Read a client report's facts","description":"What each block of the report would show today, and why a block without data is left off the paper. Publishing takes its own snapshot. Account level: a key restricted to one brand answers `403 forbidden`.","operationId":"get_client_report_facts_v1_client_reports__document_id__facts_get","parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","description":"Client report id (UUID).","title":"Document Id"},"description":"Client report id (UUID)."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Read a client report's facts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientReportFacts"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:client-reports","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/client-reports/{document_id}/versions":{"post":{"tags":["Client reports"],"summary":"Publish a client report","description":"Freeze the report's sheets, numbers, sentences and branding as its next version: the one the client sees on its link and in the portal, with its PDF rendered in the background. Account level: a key restricted to one brand answers `403 forbidden`.","operationId":"publish_client_report_v1_client_reports__document_id__versions_post","parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","description":"Client report id (UUID).","title":"Document Id"},"description":"Client report id (UUID)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"201":{"description":"Publish a client report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientReportVersion"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:client-reports","x-rankprompt-cost":{"request_units":3,"credits":0}}},"/v1/brands/{brand_id}/community-threads":{"get":{"tags":["Community"],"summary":"List community threads","description":"The Reddit, forum and LinkedIn threads the brand chose to answer, the ones the answers cite most first, with how many sit in each status under the other filters. Every plan. Offset paginated: the order comes from the answers at read time. With `place`, the citations counted are the answers asked in those places and only the threads cited there are listed.","operationId":"list_community_threads_v1_brands__brand_id__community_threads_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"enum":["open","drafted","replied","ignored"],"type":"string"}},{"type":"null"}],"description":"Only these statuses.","title":"Status"},"description":"Only these statuses."},{"name":"source_type","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"enum":["reddit","qa_forum","linkedin"],"type":"string"}},{"type":"null"}],"description":"Only these networks.","title":"Source Type"},"description":"Only these networks."},{"name":"url","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":100},{"type":"null"}],"description":"Only these threads.","title":"Url"},"description":"Only these threads."},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Words in the title or URL.","title":"Search"},"description":"Words in the title or URL."},{"name":"place","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","minLength":1,"maxLength":300},"maxItems":200},{"type":"null"}],"description":"Only the runs in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake, `australia|emerald|victoria`), across every tracker; repeat the parameter for several.","title":"Place"},"description":"Only the runs in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake, `australia|emerald|victoria`), across every tracker; repeat the parameter for several."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Threads per call (1-500, default 100).","default":100,"title":"Limit"},"description":"Threads per call (1-500, default 100)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Threads to skip.","default":0,"title":"Offset"},"description":"Threads to skip."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned community threads","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommunityThreadList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:community","x-rankprompt-cost":{"request_units":1,"credits":0}},"post":{"tags":["Community"],"summary":"Add community threads","description":"Add up to 50 threads to the brand's Community. A URL that is not a Reddit post, a forum thread or a LinkedIn post comes back in `rejected`. Requires the brand owner on Starter or with an active API subscription: `403 brand_plan_required` otherwise.","operationId":"add_community_threads_v1_brands__brand_id__community_threads_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommunityThreadsAdd"}}}},"responses":{"201":{"description":"Add community threads","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommunityThreadsAdded"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:community","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/community-threads/{thread_id}":{"patch":{"tags":["Community"],"summary":"Update a community thread","description":"Move a thread through `open`, `drafted`, `replied` and `ignored`, paste its text as `context`, or record the posted reply's link (`reply_permalink`, which marks it `replied`). Requires the brand owner on Starter or with an active API subscription: `403 brand_plan_required` otherwise.","operationId":"update_community_thread_v1_brands__brand_id__community_threads__thread_id__patch","parameters":[{"name":"thread_id","in":"path","required":true,"schema":{"type":"string","description":"Community thread id (UUID).","title":"Thread Id"},"description":"Community thread id (UUID)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommunityThreadUpdate"}}}},"responses":{"200":{"description":"Updated a community thread","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommunityThread"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:community","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/community-threads/{thread_id}/context":{"put":{"tags":["Community"],"summary":"Read a community thread","description":"Read the thread through web search, approximately, in place of its context, so a reply can be drafted. Spends the brand owner's AI budget, not credits. A thread that cannot be read answers `400`: paste its text with PATCH instead. Requires the brand owner on Starter or with an active API subscription: `403 brand_plan_required` otherwise.","operationId":"read_community_thread_v1_brands__brand_id__community_threads__thread_id__context_put","parameters":[{"name":"thread_id","in":"path","required":true,"schema":{"type":"string","description":"Community thread id (UUID).","title":"Thread Id"},"description":"Community thread id (UUID)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Read a community thread","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommunityThread"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:community","x-rankprompt-cost":{"request_units":3,"credits":0},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}}},"/v1/brands/{brand_id}/community-threads/{thread_id}/draft":{"put":{"tags":["Community"],"summary":"Draft a community reply","description":"Draft a reply to the thread in place of the last one, with a disclosure when it names the brand and how likely the community's rules frown on it. It is never posted: the user edits and posts it. Spends the brand owner's AI budget, not credits. Requires the brand owner on Starter or with an active API subscription: `403 brand_plan_required` otherwise.","operationId":"draft_community_reply_v1_brands__brand_id__community_threads__thread_id__draft_put","parameters":[{"name":"thread_id","in":"path","required":true,"schema":{"type":"string","description":"Community thread id (UUID).","title":"Thread Id"},"description":"Community thread id (UUID)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommunityDraftRequest"}}}},"responses":{"200":{"description":"Draft a community reply","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommunityThread"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:community","x-rankprompt-cost":{"request_units":3,"credits":0},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}}},"/v1/brands/{brand_id}/community-searches":{"post":{"tags":["Community"],"summary":"Search for community threads","description":"Search Google in a market (the brand's unless `country` or `language` is given) for the Reddit, forum and LinkedIn threads ranking for a keyword. Costs 1 credit when it finds threads; a search that finds none is refunded and keeps an earlier run's threads. A keyword searched before in that market reruns its saved search with fresh results and answers `200`. Requires the brand owner on Starter or with an active API subscription: `403 brand_plan_required` otherwise.","operationId":"search_community_threads_v1_brands__brand_id__community_searches_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommunitySearchRequest"}}}},"responses":{"201":{"description":"Search for community threads","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommunitySearch"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"200":{"description":"The keyword's saved search, run again with fresh results.","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"402":{"description":"Not enough credits to complete this operation","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"insufficient_credits","message":"Not enough credits to complete this operation"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:community","x-rankprompt-cost":{"request_units":2,"credits":1},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}}},"/v1/brands/{brand_id}/content-briefs/{brief_id}/outlines":{"post":{"tags":["Content"],"summary":"Outline a content brief","description":"Research the brief's topic and write its outline, saved on the brief as `outline_json`, before the full article is generated; the brief stays a draft and a later generation reuses the outline. Costs 1 credit each time. A brief without a topic or target keyword answers `400`. Requires the brand owner on Starter or with an active API subscription.","operationId":"outline_content_brief_v1_brands__brand_id__content_briefs__brief_id__outlines_post","parameters":[{"name":"brief_id","in":"path","required":true,"schema":{"type":"string","description":"Content brief id (UUID).","title":"Brief Id"},"description":"Content brief id (UUID)."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"201":{"description":"Outline a content brief","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentBrief"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"402":{"description":"Not enough credits to complete this operation","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"insufficient_credits","message":"Not enough credits to complete this operation"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:content","x-rankprompt-cost":{"request_units":3,"credits":1},"x-rankprompt-rate-limit":{"tier":"llm","api_key":"10/minute","jwt":"30/minute"}}},"/v1/brands/{brand_id}/content-calendar":{"get":{"tags":["Content"],"summary":"Read the content calendar","description":"Every article slot of the brand inside a window, each in the state the server knows it is in (planned, queued, generating, ready, scheduled, held for the owner's plan, in review, published, failed, missed), the autopilot's coming slots, and the open tasks due in the window. Each slot says whether the article is `approved` (its board task approved, or the client approved it in review), with its `task_id` to approve it through the tasks API, and a `queue` slot carries the `schedule_id` to move. `from` and `to` are ISO 8601; without them the window starts a week ago and spans 42 days, and it never spans more than 120. `place` keeps the articles written for those markets, and leaves out the tasks and the autopilot's slots, which belong to no market.","operationId":"get_content_calendar_v1_brands__brand_id__content_calendar_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}],"description":"Window start (ISO 8601).","title":"From"},"description":"Window start (ISO 8601)."},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}],"description":"Window end, exclusive (ISO 8601).","title":"To"},"description":"Window end, exclusive (ISO 8601)."},{"name":"place","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","minLength":1,"maxLength":300},"maxItems":200},{"type":"null"}],"description":"Only articles written for these markets, as `country|city` lowercased (`mexico|monterrey`, or `mexico|` for the whole country; `country|city|region` for a town keyed apart from its namesake): an article's `market.place_key`. Repeat the parameter for several.","title":"Place"},"description":"Only articles written for these markets, as `country|city` lowercased (`mexico|monterrey`, or `mexico|` for the whole country; `country|city|region` for a town keyed apart from its namesake): an article's `market.place_key`. Repeat the parameter for several."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Read the content calendar","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentCalendar"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:content","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/content-calendar/undated":{"get":{"tags":["Content"],"summary":"List the undated articles","description":"The articles that have no day on the calendar: drafts and articles ready for review with no `planned_publish_at`, no publish queued and no pull request waiting, newest change first. Date one with `PATCH /v1/brands/{brand_id}/content-briefs/{brief_id}`. Page with `limit` and `offset`.","operationId":"list_undated_articles_v1_brands__brand_id__content_calendar_undated_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Articles per page.","default":20,"title":"Limit"},"description":"Articles per page."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Articles to skip.","default":0,"title":"Offset"},"description":"Articles to skip."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned the undated articles","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UndatedArticleList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:content","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/gbp/locations":{"get":{"tags":["Google Business Profile"],"summary":"List Business Profile locations","description":"The Google Business Profile locations linked to the brand; `id` is what the other GBP calls take.","operationId":"list_gbp_locations_v1_brands__brand_id__gbp_locations_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned Business Profile locations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GbpLocationList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:gbp","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/gbp/post-schedules":{"get":{"tags":["Google Business Profile"],"summary":"List scheduled posts","description":"The brand's pending scheduled local posts across its locations, soonest first. Offset paginated.","operationId":"list_gbp_post_schedules_v1_brands__brand_id__gbp_post_schedules_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Scheduled posts per call (1-100, default 50).","default":50,"title":"Limit"},"description":"Scheduled posts per call (1-100, default 50)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Scheduled posts to skip.","default":0,"title":"Offset"},"description":"Scheduled posts to skip."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned scheduled posts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GbpPostScheduleList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:gbp","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/gbp/locations/{location_id}/post-schedules":{"post":{"tags":["Google Business Profile"],"summary":"Schedule a local post","description":"Queue a local post to publish on the location at a future time; it goes out publicly on Google then. Requires the brand owner on Starter or with an active API subscription: `403 brand_plan_required` otherwise.","operationId":"schedule_gbp_post_v1_brands__brand_id__gbp_locations__location_id__post_schedules_post","parameters":[{"name":"location_id","in":"path","required":true,"schema":{"type":"string","description":"The linked location's id, from `GET .../gbp/locations`.","title":"Location Id"},"description":"The linked location's id, from `GET .../gbp/locations`."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GbpPostScheduleCreate"}}}},"responses":{"201":{"description":"Schedule a local post","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GbpPostSchedule"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:gbp","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/gbp/locations/{location_id}/post-schedules/{schedule_id}":{"patch":{"tags":["Google Business Profile"],"summary":"Reschedule a local post","description":"Move a pending scheduled post (`scheduled`, `held` or `missed`) to a new time, replace its body, or both; give at least one. A `missed` post needs a new time, which puts it back in the queue. Any other status answers `400 validation_error`, and a post of another location or brand `404 not_found`. Requires the brand owner on Starter or with an active API subscription: `403 brand_plan_required` otherwise.","operationId":"reschedule_gbp_post_v1_brands__brand_id__gbp_locations__location_id__post_schedules__schedule_id__patch","parameters":[{"name":"location_id","in":"path","required":true,"schema":{"type":"string","description":"The linked location's id, from `GET .../gbp/locations`.","title":"Location Id"},"description":"The linked location's id, from `GET .../gbp/locations`."},{"name":"schedule_id","in":"path","required":true,"schema":{"type":"string","description":"The scheduled post's id, from `GET .../gbp/post-schedules`.","title":"Schedule Id"},"description":"The scheduled post's id, from `GET .../gbp/post-schedules`."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GbpPostScheduleUpdate"}}}},"responses":{"200":{"description":"Reschedule a local post","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GbpPostSchedule"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:gbp","x-rankprompt-cost":{"request_units":1,"credits":0}},"delete":{"tags":["Google Business Profile"],"summary":"Cancel a scheduled local post","description":"Cancel a scheduled post so it never publishes, or dismiss a `failed` one; it stays in the history as `canceled`. A post of another location or brand answers `404 not_found`; one already `published` or `publishing` answers `400 validation_error`. Canceling is never behind a plan.","operationId":"cancel_gbp_post_v1_brands__brand_id__gbp_locations__location_id__post_schedules__schedule_id__delete","parameters":[{"name":"location_id","in":"path","required":true,"schema":{"type":"string","description":"The linked location's id, from `GET .../gbp/locations`.","title":"Location Id"},"description":"The linked location's id, from `GET .../gbp/locations`."},{"name":"schedule_id","in":"path","required":true,"schema":{"type":"string","description":"The scheduled post's id, from `GET .../gbp/post-schedules`.","title":"Schedule Id"},"description":"The scheduled post's id, from `GET .../gbp/post-schedules`."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"204":{"description":"Cancel a scheduled local post","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:gbp","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/gbp/locations/{location_id}/reviews":{"get":{"tags":["Google Business Profile"],"summary":"List a location's reviews","description":"The location's Google reviews, newest first, with the reply each has, read live from Google 50 at a time. Pass `next_cursor` back as `cursor` for the next page. A brand without Google connected answers `400 google_not_connected`, an expired connection `400 google_connection_expired`.","operationId":"list_gbp_reviews_v1_brands__brand_id__gbp_locations__location_id__reviews_get","parameters":[{"name":"location_id","in":"path","required":true,"schema":{"type":"string","description":"The linked location's id, from `GET .../gbp/locations`.","title":"Location Id"},"description":"The linked location's id, from `GET .../gbp/locations`."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"description":"`next_cursor` of the previous page.","title":"Cursor"},"description":"`next_cursor` of the previous page."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned a location's reviews","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GbpReviewList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:gbp","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/gbp/locations/{location_id}/reviews/{review_id}/replies":{"post":{"tags":["Google Business Profile"],"summary":"Reply to a review","description":"Publish a reply under a Google review, in place of the one there; it is public on Google at once. Requires the brand owner on Starter or with an active API subscription: `403 brand_plan_required` otherwise. A brand without Google connected answers `400 google_not_connected`, an expired connection `400 google_connection_expired`.","operationId":"reply_to_gbp_review_v1_brands__brand_id__gbp_locations__location_id__reviews__review_id__replies_post","parameters":[{"name":"location_id","in":"path","required":true,"schema":{"type":"string","description":"The linked location's id, from `GET .../gbp/locations`.","title":"Location Id"},"description":"The linked location's id, from `GET .../gbp/locations`."},{"name":"review_id","in":"path","required":true,"schema":{"type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_-]+$","description":"Google's review id.","title":"Review Id"},"description":"Google's review id."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GbpReviewReplyCreate"}}}},"responses":{"201":{"description":"Reply to a review","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GbpReviewReply"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:gbp","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/gbp/locations/{location_id}/profile":{"get":{"tags":["Google Business Profile"],"summary":"Read a location's profile","description":"The location's Business Profile as Google has it (description, website, phone, categories, services, hours, address) and its latest `audit`: a 0 to 100 score over the checks measured, a grade and each measured check's state (`field_id` names the check, such as `hours.set`). The profile is read from Google and kept for 72 hours; the audit runs every week and on the first read. A brand without Google connected answers `400 google_not_connected`, an expired connection `400 google_connection_expired`.","operationId":"get_gbp_profile_v1_brands__brand_id__gbp_locations__location_id__profile_get","parameters":[{"name":"location_id","in":"path","required":true,"schema":{"type":"string","description":"The linked location's id, from `GET .../gbp/locations`.","title":"Location Id"},"description":"The linked location's id, from `GET .../gbp/locations`."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Read a location's profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GbpProfile"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:gbp","x-rankprompt-cost":{"request_units":2,"credits":0}},"patch":{"tags":["Google Business Profile"],"summary":"Update a location's profile","description":"Write profile fields to Google: the description (750 characters at most; refused for the kinds of business Google locks it on, see `description_locked`), the website, the phone, the hours, the primary and additional categories and the services. Only the fields given change, and the change is public on Google at once. Answers the profile as Google keeps it. Requires the brand owner on Starter or with an active API subscription: `403 brand_plan_required` otherwise. A brand without Google connected answers `400 google_not_connected`, an expired connection `400 google_connection_expired`.","operationId":"update_gbp_profile_v1_brands__brand_id__gbp_locations__location_id__profile_patch","parameters":[{"name":"location_id","in":"path","required":true,"schema":{"type":"string","description":"The linked location's id, from `GET .../gbp/locations`.","title":"Location Id"},"description":"The linked location's id, from `GET .../gbp/locations`."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GbpProfileUpdate"}}}},"responses":{"200":{"description":"Updated a location's profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GbpProfile"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:gbp","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/gbp/locations/{location_id}/performance":{"get":{"tags":["Google Business Profile"],"summary":"Read a location's performance","description":"How people found and acted on the location on Google, one row a day: impressions on Maps and Search by device, website clicks, calls, direction requests, bookings, food orders and conversations, with each summed over the window (`totals`) and over the window before (`totals_prev`). `include=keywords` adds the searches people used to find it in `month` (`YYYY-MM`, the current month by default), with their impressions. `start_date` and `end_date` are `YYYY-MM-DD`, the last 28 days by default. A brand without Google connected answers `400 google_not_connected`, an expired connection `400 google_connection_expired`.","operationId":"get_gbp_performance_v1_brands__brand_id__gbp_locations__location_id__performance_get","parameters":[{"name":"location_id","in":"path","required":true,"schema":{"type":"string","description":"The linked location's id, from `GET .../gbp/locations`.","title":"Location Id"},"description":"The linked location's id, from `GET .../gbp/locations`."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"description":"First day (YYYY-MM-DD).","title":"Start Date"},"description":"First day (YYYY-MM-DD)."},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"description":"Last day (YYYY-MM-DD).","title":"End Date"},"description":"Last day (YYYY-MM-DD)."},{"name":"include","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"const":"keywords","type":"string"}},{"type":"null"}],"description":"`keywords` adds the month's searches.","title":"Include"},"description":"`keywords` adds the month's searches."},{"name":"month","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}$"},{"type":"null"}],"description":"With `include=keywords`, the month (YYYY-MM).","title":"Month"},"description":"With `include=keywords`, the month (YYYY-MM)."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Read a location's performance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GbpPerformance"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:gbp","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/gbp/locations/{location_id}/local-pilot":{"get":{"tags":["Google Business Profile"],"summary":"Read a location's local pilot","description":"The weekly local pilot of the location: whether it is on, whether replies to 4 and 5 star reviews publish on their own, this month's drafts against the caps included in Starter, and how many drafts wait for approval in the app.","operationId":"get_local_pilot_v1_brands__brand_id__gbp_locations__location_id__local_pilot_get","parameters":[{"name":"location_id","in":"path","required":true,"schema":{"type":"string","description":"The linked location's id, from `GET .../gbp/locations`.","title":"Location Id"},"description":"The linked location's id, from `GET .../gbp/locations`."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Read a location's local pilot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocalPilot"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:gbp","x-rankprompt-cost":{"request_units":1,"credits":0}},"put":{"tags":["Google Business Profile"],"summary":"Configure a location's local pilot","description":"Turn the weekly local pilot on or off, and choose whether replies to 4 and 5 star reviews publish without approval (replies to 1 to 3 stars always wait for a person). Turned on, its first week is drafted within the hour. Included in Starter, no credits. Requires the brand owner on Starter or with an active API subscription: `403 brand_plan_required` otherwise.","operationId":"configure_local_pilot_v1_brands__brand_id__gbp_locations__location_id__local_pilot_put","parameters":[{"name":"location_id","in":"path","required":true,"schema":{"type":"string","description":"The linked location's id, from `GET .../gbp/locations`.","title":"Location Id"},"description":"The linked location's id, from `GET .../gbp/locations`."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocalPilotUpdate"}}}},"responses":{"200":{"description":"Configure a location's local pilot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocalPilot"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:gbp","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/gbp/locations/{location_id}/gbp-audits/latest":{"get":{"tags":["Google Business Profile"],"summary":"Read a location's latest Business Profile audit","description":"The newest audit of the location's Business Profile: the 0 to 100 score over the checks it could measure, the coverage (`measured` of `total`), the count per status and every check with what it found and how the app fixes it. A location never audited answers `404 not_found`; run one with `POST .../gbp-audits`.","operationId":"get_latest_gbp_audit_v1_brands__brand_id__gbp_locations__location_id__gbp_audits_latest_get","parameters":[{"name":"location_id","in":"path","required":true,"schema":{"type":"string","description":"The linked location's id, from `GET .../gbp/locations`.","title":"Location Id"},"description":"The linked location's id, from `GET .../gbp/locations`."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Read a location's latest Business Profile audit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GbpAuditRun"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:gbp","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/gbp/locations/{location_id}/gbp-audits":{"post":{"tags":["Google Business Profile"],"summary":"Audit a location's Business Profile","description":"Audit the location's Business Profile now: its profile, photos, posts and reviews against the top 3 of the place's latest map scan (fixed targets without one). Free, at most once an hour per location (`429` otherwise). Failures that need the user open tasks in the `LOCAL` category. A brand without Google connected answers `400 google_not_connected`, an expired connection `400 google_connection_expired`.","operationId":"run_gbp_audit_v1_brands__brand_id__gbp_locations__location_id__gbp_audits_post","parameters":[{"name":"location_id","in":"path","required":true,"schema":{"type":"string","description":"The linked location's id, from `GET .../gbp/locations`.","title":"Location Id"},"description":"The linked location's id, from `GET .../gbp/locations`."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"201":{"description":"Audit a location's Business Profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GbpAuditRun"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:gbp","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/merchant-center":{"get":{"tags":["Merchant Center"],"summary":"Get the Merchant Center feed health","description":"Whether the brand's Google grant covers Merchant Center, the account its products come from, when they were last read and the feed's health: disapproved and pending products, missing GTIN or brand, prices Google found different on the landing page, out of stock, and the issues most products carry. `health` is null until the products have been read once (the app reads them when the account is picked). Products a week old are read again in the background when they are asked for, and this answer serves the stored ones meanwhile. Single object.","operationId":"get_merchant_center_v1_brands__brand_id__merchant_center_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned the Merchant Center feed health","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantCenter"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:merchant-center","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/merchant-center/products":{"get":{"tags":["Merchant Center"],"summary":"List the Merchant Center products","description":"The products of the brand's Merchant Center account as last read, by title then resource name, with price, availability, GTINs, approval and Google's item level issues. `view` keeps the products with one problem. The list is replaced on every read from Google, so it pages with `limit` and `offset` and returns `total`. A brand without Google connected, or whose grant lacks Merchant Center, answers `400` with the connect action. Free: no credits.","operationId":"list_merchant_products_v1_brands__brand_id__merchant_center_products_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"view","in":"query","required":false,"schema":{"enum":["all","disapproved","missing_gtin","missing_brand","price_mismatch","out_of_stock"],"type":"string","description":"Only the products with this problem.","default":"all","title":"View"},"description":"Only the products with this problem."},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Only titles holding this text.","title":"Search"},"description":"Only titles holding this text."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned the Merchant Center products","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantProductPage"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:merchant-center","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/merchant-center/prompt-suggestions":{"get":{"tags":["Merchant Center"],"summary":"Suggest shopping prompts from the catalog","description":"Shopping prompts a buyer asks an AI engine before buying one of the brand's products, built from the stored catalog in the brand's market language: `best <category> under <price>` per category with two or more products in stock, then a review prompt for the most specific product names. Add them to a report with `POST /v1/brands/{brand_id}/reports/{report_id}/prompts` to track whether AI recommends the products. Not paginated. A brand without Google connected, or whose grant lacks Merchant Center, answers `400` with the connect action. Free: no credits.","operationId":"list_product_prompt_suggestions_v1_brands__brand_id__merchant_center_prompt_suggestions_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Suggest shopping prompts from the catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductPromptList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:merchant-center","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/merchant-center/mentions":{"get":{"tags":["Merchant Center"],"summary":"List the products a run's answers named","description":"The catalog's products the answers of one run named, by their model name as whole words (a category alone names nothing), with how many answers, the AI platforms and up to five prompts. `report_id` is a run; left out, the brand's latest completed run. Reads the answers too, so it also needs `read:reports`. Not paginated. A brand without Google connected, or whose grant lacks Merchant Center, answers `400` with the connect action. Free: no credits.","operationId":"list_product_mentions_v1_brands__brand_id__merchant_center_mentions_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"report_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"One run; the latest completed one when left out.","title":"Report Id"},"description":"One run; the latest completed one when left out."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned the products a run's answers named","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductMentionList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:merchant-center","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/youtube":{"get":{"tags":["YouTube"],"summary":"Get the YouTube channel and its AI citations","description":"The brand's own YouTube channel and its public uploads (views, captions, chapters) with how many AI answers cited each in the last 90 days; the other channels' videos cited in answers that left the brand out, with their prompts; the first ten prompts to answer in a video and `gap_count`, how many there are. `channel_id` is null until a channel is picked in the app, and `videos` empty until it has been read. Uploads a week old are read again in the background when they are asked for, and this answer serves the stored ones meanwhile. Reads the cited videos too, so it also needs `read:citations`. Free: no credits. Single object.","operationId":"get_youtube_channel_v1_brands__brand_id__youtube_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned the YouTube channel and its AI citations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/YouTubeChannel"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:youtube","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/youtube/gaps":{"get":{"tags":["YouTube"],"summary":"List the prompts to answer in a video","description":"The prompts whose AI answers of the last 90 days cited another channel's YouTube video and left the brand out, most such answers first, then by prompt, with how many videos those answers cited and their AI platforms. Grouped from the answers at read time, so it pages with `limit` and `offset` and returns `total`. Reads the cited videos too, so it also needs `read:citations`. Free: no credits.","operationId":"list_youtube_gaps_v1_brands__brand_id__youtube_gaps_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"default":20,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned the prompts to answer in a video","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoGapPage"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:youtube","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/youtube/tasks":{"post":{"tags":["YouTube"],"summary":"Suggest the YouTube channel's tasks","description":"Suggests one task for the public uploads without captions, or without chapters when they are long enough for three (the YouTube channel page names them), and one for each of the first ten prompts to answer in a video. Each lands once: asking again creates only the new ones and updates the others where they are. Needs `write:tasks` and `read:youtube`. Free: no credits.","operationId":"create_youtube_tasks_v1_brands__brand_id__youtube_tasks_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Suggest the YouTube channel's tasks","content":{"application/json":{"schema":{"$ref":"#/components/schemas/YouTubeTasks"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:tasks","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/data-studio/sources":{"get":{"tags":["Data Studio"],"summary":"List the Data Studio sources","description":"Every source the Data Studio connector offers: its path, the scope a key needs to read it, how its pages chain and its columns with their types, so the connector's schema follows this list. Any plan; reading the rows needs Agency or Agency Plus.","operationId":"list_sources_v1_data_studio_sources_get","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned the Data Studio sources","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataStudioSourceList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:brands","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/data-studio/brands":{"get":{"tags":["Data Studio"],"summary":"Brands for Data Studio","description":"One row per brand of the account the key acts in, newest first, with its newest visibility score in the period (a run of several markets pooled into one score). A key restricted to one brand lists that brand. `date_from` and `date_to` are days, both inclusive, read in UTC: the date range Data Studio sends. `date_to` is at most 366 days after `date_from`; a longer range answers `400 validation_error`. Cursor paginated via `limit` (1-500) and `cursor`. Agency and Agency Plus: another plan answers `403 account_plan_required`. Free: no credits.","operationId":"list_data_studio_brands_v1_data_studio_brands_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Rows per page (1-500, default 100).","default":100,"title":"Limit"},"description":"Rows per page (1-500, default 100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Continuation token from a previous response's `next_cursor`.","title":"Cursor"},"description":"Continuation token from a previous response's `next_cursor`."},{"name":"date_from","in":"query","required":true,"schema":{"type":"string","format":"date","description":"First day of the period (`YYYY-MM-DD`), inclusive.","title":"Date From"},"description":"First day of the period (`YYYY-MM-DD`), inclusive."},{"name":"date_to","in":"query","required":true,"schema":{"type":"string","format":"date","description":"Last day of the period (`YYYY-MM-DD`), inclusive.","title":"Date To"},"description":"Last day of the period (`YYYY-MM-DD`), inclusive."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Brands for Data Studio","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataStudioBrandList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:brands","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/data-studio/reports":{"get":{"tags":["Data Studio"],"summary":"Reports with score for Data Studio","description":"One row per completed report of the brand in the period, newest first: one run in one market, with its visibility score, prompts ranked and asked, answers and engines, named as the PDF report's run history names them. `date_from` and `date_to` are days, both inclusive, read in UTC: the date range Data Studio sends. `date_to` is at most 366 days after `date_from`; a longer range answers `400 validation_error`. Cursor paginated via `limit` (1-500) and `cursor`. Agency and Agency Plus: a brand whose owner is on a lower plan answers `403 brand_plan_required`. Free: no credits.","operationId":"list_data_studio_reports_v1_data_studio_reports_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Rows per page (1-500, default 100).","default":100,"title":"Limit"},"description":"Rows per page (1-500, default 100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Continuation token from a previous response's `next_cursor`.","title":"Cursor"},"description":"Continuation token from a previous response's `next_cursor`."},{"name":"date_from","in":"query","required":true,"schema":{"type":"string","format":"date","description":"First day of the period (`YYYY-MM-DD`), inclusive.","title":"Date From"},"description":"First day of the period (`YYYY-MM-DD`), inclusive."},{"name":"date_to","in":"query","required":true,"schema":{"type":"string","format":"date","description":"Last day of the period (`YYYY-MM-DD`), inclusive.","title":"Date To"},"description":"Last day of the period (`YYYY-MM-DD`), inclusive."},{"name":"brand_id","in":"query","required":true,"schema":{"type":"string","description":"Brand UUID to scope the listing. **Required.**","examples":["b3d2c1a0-1234-4abc-9def-0123456789ab"],"title":"Brand Id"},"description":"Brand UUID to scope the listing. **Required.**"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Reports with score for Data Studio","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataStudioReportList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:reports","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/data-studio/prompts":{"get":{"tags":["Data Studio"],"summary":"Prompts and platforms for Data Studio","description":"One row per prompt of the brand and AI platform that answered it in the brand's completed reports in the period: the answers, how many named the brand, that share and the brand's mean position, named as the PDF report's position by engine names them. Prompts in alphabetical order. `date_from` and `date_to` are days, both inclusive, read in UTC: the date range Data Studio sends. `date_to` is at most 366 days after `date_from`; a longer range answers `400 validation_error`. Offset paginated by prompts: `limit` (1-500), `offset` and `total` count prompts, each giving a row per engine. Agency and Agency Plus: a brand whose owner is on a lower plan answers `403 brand_plan_required`. Free: no credits.","operationId":"list_data_studio_prompts_v1_data_studio_prompts_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Prompts per page (1-500, default 100).","default":100,"title":"Limit"},"description":"Prompts per page (1-500, default 100)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Prompts to skip.","default":0,"title":"Offset"},"description":"Prompts to skip."},{"name":"date_from","in":"query","required":true,"schema":{"type":"string","format":"date","description":"First day of the period (`YYYY-MM-DD`), inclusive.","title":"Date From"},"description":"First day of the period (`YYYY-MM-DD`), inclusive."},{"name":"date_to","in":"query","required":true,"schema":{"type":"string","format":"date","description":"Last day of the period (`YYYY-MM-DD`), inclusive.","title":"Date To"},"description":"Last day of the period (`YYYY-MM-DD`), inclusive."},{"name":"brand_id","in":"query","required":true,"schema":{"type":"string","description":"Brand UUID to scope the listing. **Required.**","examples":["b3d2c1a0-1234-4abc-9def-0123456789ab"],"title":"Brand Id"},"description":"Brand UUID to scope the listing. **Required.**"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Prompts and platforms for Data Studio","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataStudioPromptList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:reports","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/data-studio/citations":{"get":{"tags":["Data Studio"],"summary":"Citations by domain for Data Studio","description":"One row per domain the answers in the brand's completed reports cited in the period, most cited first, named as the PDF report's citation sources name them. `date_from` and `date_to` are days, both inclusive, read in UTC: the date range Data Studio sends. `date_to` is at most 366 days after `date_from`; a longer range answers `400 validation_error`. Offset paginated via `limit` (1-500) and `offset`: the rows are counted from the answers at read time. Agency and Agency Plus: a brand whose owner is on a lower plan answers `403 brand_plan_required`. Free: no credits.","operationId":"list_data_studio_citations_v1_data_studio_citations_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Rows per page (1-500, default 100).","default":100,"title":"Limit"},"description":"Rows per page (1-500, default 100)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip.","default":0,"title":"Offset"},"description":"Rows to skip."},{"name":"date_from","in":"query","required":true,"schema":{"type":"string","format":"date","description":"First day of the period (`YYYY-MM-DD`), inclusive.","title":"Date From"},"description":"First day of the period (`YYYY-MM-DD`), inclusive."},{"name":"date_to","in":"query","required":true,"schema":{"type":"string","format":"date","description":"Last day of the period (`YYYY-MM-DD`), inclusive.","title":"Date To"},"description":"Last day of the period (`YYYY-MM-DD`), inclusive."},{"name":"brand_id","in":"query","required":true,"schema":{"type":"string","description":"Brand UUID to scope the listing. **Required.**","examples":["b3d2c1a0-1234-4abc-9def-0123456789ab"],"title":"Brand Id"},"description":"Brand UUID to scope the listing. **Required.**"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Citations by domain for Data Studio","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataStudioCitationList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:citations","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/data-studio/competitors":{"get":{"tags":["Data Studio"],"summary":"Competitors for Data Studio","description":"The brand, then its direct and indirect competitors the answers in its completed reports named in the period, most mentioned first, with their share of voice and its change, named as the PDF report's share of voice names them. Competitors are read through the directory: an alias counts under its competitor. `date_from` and `date_to` are days, both inclusive, read in UTC: the date range Data Studio sends. `date_to` is at most 366 days after `date_from`; a longer range answers `400 validation_error`. Offset paginated via `limit` (1-500) and `offset`: the rows are counted from the answers at read time. Agency and Agency Plus: a brand whose owner is on a lower plan answers `403 brand_plan_required`. Free: no credits.","operationId":"list_data_studio_competitors_v1_data_studio_competitors_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Rows per page (1-500, default 100).","default":100,"title":"Limit"},"description":"Rows per page (1-500, default 100)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip.","default":0,"title":"Offset"},"description":"Rows to skip."},{"name":"date_from","in":"query","required":true,"schema":{"type":"string","format":"date","description":"First day of the period (`YYYY-MM-DD`), inclusive.","title":"Date From"},"description":"First day of the period (`YYYY-MM-DD`), inclusive."},{"name":"date_to","in":"query","required":true,"schema":{"type":"string","format":"date","description":"Last day of the period (`YYYY-MM-DD`), inclusive.","title":"Date To"},"description":"Last day of the period (`YYYY-MM-DD`), inclusive."},{"name":"brand_id","in":"query","required":true,"schema":{"type":"string","description":"Brand UUID to scope the listing. **Required.**","examples":["b3d2c1a0-1234-4abc-9def-0123456789ab"],"title":"Brand Id"},"description":"Brand UUID to scope the listing. **Required.**"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Competitors for Data Studio","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataStudioCompetitorList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:competitors","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/data-studio/weekly-moves":{"get":{"tags":["Data Studio"],"summary":"Weekly moves for Data Studio","description":"What the weekly digest says moved, line by line: for the newest run of each week in each place in the period, newest first, a `score` row (the score, the four week average, the band a rerun would land in and whether the score left it), then a row per prompt won or lost on an engine, per domain newly cited or no longer cited and per competitor that moved, each against the run before it in that place. `date_from` and `date_to` are days, both inclusive, read in UTC: the date range Data Studio sends. `date_to` is at most 366 days after `date_from`; a longer range answers `400 validation_error`. Offset paginated by runs: `limit` (1-20, default 10), `offset` and `total` count runs, each giving one row or more. Agency and Agency Plus: a brand whose owner is on a lower plan answers `403 brand_plan_required`. Free: no credits.","operationId":"list_data_studio_weekly_moves_v1_data_studio_weekly_moves_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":20,"minimum":1,"description":"Runs per page (1-20, default 10).","default":10,"title":"Limit"},"description":"Runs per page (1-20, default 10)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Runs to skip.","default":0,"title":"Offset"},"description":"Runs to skip."},{"name":"date_from","in":"query","required":true,"schema":{"type":"string","format":"date","description":"First day of the period (`YYYY-MM-DD`), inclusive.","title":"Date From"},"description":"First day of the period (`YYYY-MM-DD`), inclusive."},{"name":"date_to","in":"query","required":true,"schema":{"type":"string","format":"date","description":"Last day of the period (`YYYY-MM-DD`), inclusive.","title":"Date To"},"description":"Last day of the period (`YYYY-MM-DD`), inclusive."},{"name":"brand_id","in":"query","required":true,"schema":{"type":"string","description":"Brand UUID to scope the listing. **Required.**","examples":["b3d2c1a0-1234-4abc-9def-0123456789ab"],"title":"Brand Id"},"description":"Brand UUID to scope the listing. **Required.**"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Weekly moves for Data Studio","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataStudioWeeklyMoveList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:reports","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/github/publishing-profile":{"get":{"tags":["Content"],"summary":"Read the GitHub publishing profile","description":"How the brand's connected GitHub repository takes articles, as saved: status, posts folder and file name, format, frontmatter keys, images, post URL, locales, branch and whether posts open a pull request or commit directly. Nothing is read from GitHub. Brand owner or editor. A brand without a connected repository answers `400 integration_not_connected`.","operationId":"get_github_publishing_profile_v1_brands__brand_id__github_publishing_profile_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Read the GitHub publishing profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GitHubPublishingProfile"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:cms","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/github/publishing-profile-inferences":{"post":{"tags":["Content"],"summary":"Read the repository's blog again","description":"Read the connected repository and save how its blog is laid out, replacing what was read before; the owner's corrections, the branch and the commit mode are kept. A repository without a blog comes back `no_blog`: add one with `POST .../github/blog-scaffolds`. Brand owner only, on Starter or with an active API subscription: `403 brand_plan_required` otherwise. A brand without a connected repository answers `400 integration_not_connected` with the page to connect it.","operationId":"infer_github_publishing_profile_v1_brands__brand_id__github_publishing_profile_inferences_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"201":{"description":"Read the repository's blog again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GitHubPublishingProfile"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:cms","x-rankprompt-cost":{"request_units":3,"credits":0}}},"/v1/brands/{brand_id}/github/blog-scaffolds":{"post":{"tags":["Content"],"summary":"Add a blog to the repository","description":"Open a pull request on the connected repository that adds a minimal blog following its framework (Astro, Next.js app router, Hugo, Jekyll) and layout. Only when the profile is `no_blog`; the repository becomes a publish target once it merges. A blog already there or a pull request already open answers `409`. Brand owner only, on Starter or with an active API subscription: `403 brand_plan_required` otherwise. A brand without a connected repository answers `400 integration_not_connected` with the page to connect it.","operationId":"scaffold_github_blog_v1_brands__brand_id__github_blog_scaffolds_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"201":{"description":"Add a blog to the repository","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GitHubBlogScaffold"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:cms","x-rankprompt-cost":{"request_units":3,"credits":0}}},"/v1/brands/{brand_id}/citations/offsite":{"get":{"tags":["Citations"],"summary":"Off-site summary","description":"Per kind of third-party site the answers cited: its pages, how many a page analysis read, and the brand and competitors the analyzed ones name, with their sentiment. Filters compose with AND: `report_id` (repeat for several), `scheduled_report_id`, `platform` (repeat for several engines), `date_from`, `date_to` and `category`.","operationId":"get_offsite_summary_v1_brands__brand_id__citations_offsite_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"source_type","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"enum":["owned","competitor","reddit","youtube","linkedin","wikipedia","qa_forum","social","news","reviews","reference","institutional","company","marketplace","google_place","google_product","other","classifying"],"type":"string"}},{"type":"null"}],"description":"Only these kinds of site; repeat for several.","title":"Source Type"},"description":"Only these kinds of site; repeat for several."},{"name":"report_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Only these reports (UUIDs); repeat the parameter for several.","title":"Report Id"},"description":"Only these reports (UUIDs); repeat the parameter for several."},{"name":"report_scope","in":"query","required":false,"schema":{"anyOf":[{"const":"all","type":"string"},{"type":"null"}],"description":"`all` for every completed report of the brand, in place of naming each one; the other filters still apply.","title":"Report Scope"},"description":"`all` for every completed report of the brand, in place of naming each one; the other filters still apply."},{"name":"scheduled_report_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only the runs of this Scheduled Report (UUID).","title":"Scheduled Report Id"},"description":"Only the runs of this Scheduled Report (UUID)."},{"name":"tracker_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":200},{"type":"null"}],"description":"Only the runs of these trackers (a report's `tracker_id`; a scheduled report's id is its tracker's); repeat the parameter for several.","title":"Tracker Id"},"description":"Only the runs of these trackers (a report's `tracker_id`; a scheduled report's id is its tracker's); repeat the parameter for several."},{"name":"market_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":200},{"type":"null"}],"description":"Only the runs in these markets (a report's `market_id`, a region config's `id`); repeat the parameter for several.","title":"Market Id"},"description":"Only the runs in these markets (a report's `market_id`, a region config's `id`); repeat the parameter for several."},{"name":"place","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","minLength":1,"maxLength":300},"maxItems":200},{"type":"null"}],"description":"Only the runs in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake, `australia|emerald|victoria`), across every tracker; repeat the parameter for several.","title":"Place"},"description":"Only the runs in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake, `australia|emerald|victoria`), across every tracker; repeat the parameter for several."},{"name":"scope","in":"query","required":false,"schema":{"anyOf":[{"enum":["default","all"],"type":"string"},{"type":"null"}],"description":"`default` reads what the app opens on (every scheduled report's runs plus the newest one-off reports) and takes no other report, tracker, market or place filter; `all` reads every completed report of the brand.","title":"Scope"},"description":"`default` reads what the app opens on (every scheduled report's runs plus the newest one-off reports) and takes no other report, tracker, market or place filter; `all` reads every completed report of the brand."},{"name":"platform","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"enum":["chatgpt","chatgpt_search","perplexity","ai_overviews","claude","claude_search","gemini","grok","muse"],"type":"string"}},{"type":"null"}],"description":"Only answers from these engines; repeat the parameter for several.","title":"Platform"},"description":"Only answers from these engines; repeat the parameter for several."},{"name":"date_from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only answers from this moment on (ISO-8601).","title":"Date From"},"description":"Only answers from this moment on (ISO-8601)."},{"name":"date_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only answers before this moment, exclusive (ISO-8601); not before `date_from`.","title":"Date To"},"description":"Only answers before this moment, exclusive (ISO-8601); not before `date_from`."},{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","maxLength":200},"maxItems":50},{"type":"null"}],"description":"Only answers to prompts of these categories; repeat the parameter for several.","title":"Category"},"description":"Only answers to prompts of these categories; repeat the parameter for several."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Off-site summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OffsiteSummary"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:citations","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/citations/offsite/pages":{"get":{"tags":["Citations"],"summary":"List off-site pages","description":"The cited third-party pages with what a page analysis found they say about the brand and its competitors. `mention` keeps pages that name the brand (`brand`), a competitor and not the brand (`gap`), neither (`neither`) or were not analyzed yet (`not_analyzed`). Whether a page names anyone is known only once it was analyzed. Offset paginated: the list is ranked from the answers at read time, with a total up front. Filters compose with AND: `report_id` (repeat for several), `scheduled_report_id`, `platform` (repeat for several engines), `date_from`, `date_to` and `category`.","operationId":"list_offsite_pages_v1_brands__brand_id__citations_offsite_pages_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"source_type","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"enum":["owned","competitor","reddit","youtube","linkedin","wikipedia","qa_forum","social","news","reviews","reference","institutional","company","marketplace","google_place","google_product","other","classifying"],"type":"string"}},{"type":"null"}],"description":"Only these kinds of site; repeat for several.","title":"Source Type"},"description":"Only these kinds of site; repeat for several."},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Words in the URL or title.","title":"Search"},"description":"Words in the URL or title."},{"name":"mention","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"enum":["brand","gap","neither","not_analyzed","unlinked","analyzed","competitors"],"type":"string"}},{"type":"null"}],"description":"Only pages in these groups; repeat for several.","title":"Mention"},"description":"Only pages in these groups; repeat for several."},{"name":"competitor_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Only pages that name one of these competitors.","title":"Competitor Id"},"description":"Only pages that name one of these competitors."},{"name":"sort","in":"query","required":false,"schema":{"enum":["citations","last_seen","prompts"],"type":"string","description":"Order of the rows.","default":"citations","title":"Sort"},"description":"Order of the rows."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Pages per call (1-500, default 100).","default":100,"title":"Limit"},"description":"Pages per call (1-500, default 100)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Pages to skip.","default":0,"title":"Offset"},"description":"Pages to skip."},{"name":"report_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Only these reports (UUIDs); repeat the parameter for several.","title":"Report Id"},"description":"Only these reports (UUIDs); repeat the parameter for several."},{"name":"report_scope","in":"query","required":false,"schema":{"anyOf":[{"const":"all","type":"string"},{"type":"null"}],"description":"`all` for every completed report of the brand, in place of naming each one; the other filters still apply.","title":"Report Scope"},"description":"`all` for every completed report of the brand, in place of naming each one; the other filters still apply."},{"name":"scheduled_report_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only the runs of this Scheduled Report (UUID).","title":"Scheduled Report Id"},"description":"Only the runs of this Scheduled Report (UUID)."},{"name":"tracker_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":200},{"type":"null"}],"description":"Only the runs of these trackers (a report's `tracker_id`; a scheduled report's id is its tracker's); repeat the parameter for several.","title":"Tracker Id"},"description":"Only the runs of these trackers (a report's `tracker_id`; a scheduled report's id is its tracker's); repeat the parameter for several."},{"name":"market_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":200},{"type":"null"}],"description":"Only the runs in these markets (a report's `market_id`, a region config's `id`); repeat the parameter for several.","title":"Market Id"},"description":"Only the runs in these markets (a report's `market_id`, a region config's `id`); repeat the parameter for several."},{"name":"place","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","minLength":1,"maxLength":300},"maxItems":200},{"type":"null"}],"description":"Only the runs in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake, `australia|emerald|victoria`), across every tracker; repeat the parameter for several.","title":"Place"},"description":"Only the runs in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake, `australia|emerald|victoria`), across every tracker; repeat the parameter for several."},{"name":"scope","in":"query","required":false,"schema":{"anyOf":[{"enum":["default","all"],"type":"string"},{"type":"null"}],"description":"`default` reads what the app opens on (every scheduled report's runs plus the newest one-off reports) and takes no other report, tracker, market or place filter; `all` reads every completed report of the brand.","title":"Scope"},"description":"`default` reads what the app opens on (every scheduled report's runs plus the newest one-off reports) and takes no other report, tracker, market or place filter; `all` reads every completed report of the brand."},{"name":"platform","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"enum":["chatgpt","chatgpt_search","perplexity","ai_overviews","claude","claude_search","gemini","grok","muse"],"type":"string"}},{"type":"null"}],"description":"Only answers from these engines; repeat the parameter for several.","title":"Platform"},"description":"Only answers from these engines; repeat the parameter for several."},{"name":"date_from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only answers from this moment on (ISO-8601).","title":"Date From"},"description":"Only answers from this moment on (ISO-8601)."},{"name":"date_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only answers before this moment, exclusive (ISO-8601); not before `date_from`.","title":"Date To"},"description":"Only answers before this moment, exclusive (ISO-8601); not before `date_from`."},{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","maxLength":200},"maxItems":50},{"type":"null"}],"description":"Only answers to prompts of these categories; repeat the parameter for several.","title":"Category"},"description":"Only answers to prompts of these categories; repeat the parameter for several."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned off-site pages","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OffsitePageList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:citations","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/citations/authors":{"get":{"tags":["Citations"],"summary":"List cited authors","description":"The people who wrote the pages the answers cite, most cited first: the page authors a page analysis or a contact search found (with `contact_id`), else the byline a page names (`contact_id` null). `contacts_only=true` keeps the ones with a contact, the people to pitch. `search` matches the name, email or company. `sort`: `citations` (default), `pages`, `prompts` or `last_seen`. One author's pages: `GET /v1/brands/{brand_id}/citations/authors/{author_key}/pages`. Offset paginated: authors are grouped from the answers at read time, with a total up front. Filters compose with AND: `report_id` (repeat for several), `scheduled_report_id`, `platform` (repeat for several engines), `date_from`, `date_to` and `category`.","operationId":"list_cited_authors_v1_brands__brand_id__citations_authors_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"contacts_only","in":"query","required":false,"schema":{"type":"boolean","description":"Only authors with a contact. Default `false`.","default":false,"title":"Contacts Only"},"description":"Only authors with a contact. Default `false`."},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Words in the name, email or company.","title":"Search"},"description":"Words in the name, email or company."},{"name":"sort","in":"query","required":false,"schema":{"enum":["citations","pages","prompts","last_seen"],"type":"string","description":"Order of the rows.","default":"citations","title":"Sort"},"description":"Order of the rows."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Authors per call (1-500, default 100).","default":100,"title":"Limit"},"description":"Authors per call (1-500, default 100)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Authors to skip.","default":0,"title":"Offset"},"description":"Authors to skip."},{"name":"report_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Only these reports (UUIDs); repeat the parameter for several.","title":"Report Id"},"description":"Only these reports (UUIDs); repeat the parameter for several."},{"name":"report_scope","in":"query","required":false,"schema":{"anyOf":[{"const":"all","type":"string"},{"type":"null"}],"description":"`all` for every completed report of the brand, in place of naming each one; the other filters still apply.","title":"Report Scope"},"description":"`all` for every completed report of the brand, in place of naming each one; the other filters still apply."},{"name":"scheduled_report_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only the runs of this Scheduled Report (UUID).","title":"Scheduled Report Id"},"description":"Only the runs of this Scheduled Report (UUID)."},{"name":"tracker_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":200},{"type":"null"}],"description":"Only the runs of these trackers (a report's `tracker_id`; a scheduled report's id is its tracker's); repeat the parameter for several.","title":"Tracker Id"},"description":"Only the runs of these trackers (a report's `tracker_id`; a scheduled report's id is its tracker's); repeat the parameter for several."},{"name":"market_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":200},{"type":"null"}],"description":"Only the runs in these markets (a report's `market_id`, a region config's `id`); repeat the parameter for several.","title":"Market Id"},"description":"Only the runs in these markets (a report's `market_id`, a region config's `id`); repeat the parameter for several."},{"name":"place","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","minLength":1,"maxLength":300},"maxItems":200},{"type":"null"}],"description":"Only the runs in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake, `australia|emerald|victoria`), across every tracker; repeat the parameter for several.","title":"Place"},"description":"Only the runs in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake, `australia|emerald|victoria`), across every tracker; repeat the parameter for several."},{"name":"scope","in":"query","required":false,"schema":{"anyOf":[{"enum":["default","all"],"type":"string"},{"type":"null"}],"description":"`default` reads what the app opens on (every scheduled report's runs plus the newest one-off reports) and takes no other report, tracker, market or place filter; `all` reads every completed report of the brand.","title":"Scope"},"description":"`default` reads what the app opens on (every scheduled report's runs plus the newest one-off reports) and takes no other report, tracker, market or place filter; `all` reads every completed report of the brand."},{"name":"platform","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"enum":["chatgpt","chatgpt_search","perplexity","ai_overviews","claude","claude_search","gemini","grok","muse"],"type":"string"}},{"type":"null"}],"description":"Only answers from these engines; repeat the parameter for several.","title":"Platform"},"description":"Only answers from these engines; repeat the parameter for several."},{"name":"date_from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only answers from this moment on (ISO-8601).","title":"Date From"},"description":"Only answers from this moment on (ISO-8601)."},{"name":"date_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only answers before this moment, exclusive (ISO-8601); not before `date_from`.","title":"Date To"},"description":"Only answers before this moment, exclusive (ISO-8601); not before `date_from`."},{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","maxLength":200},"maxItems":50},{"type":"null"}],"description":"Only answers to prompts of these categories; repeat the parameter for several.","title":"Category"},"description":"Only answers to prompts of these categories; repeat the parameter for several."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned cited authors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CitedAuthorList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:citations","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/citations/authors/{author_key}/pages":{"get":{"tags":["Citations"],"summary":"List one author's cited pages","description":"The pages one author wrote that the answers cited, most cited first, each with its citations, prompts and engines. `author_key` is a `/citations/authors` row's, URL-encoded. An author with no cited page under the filters answers an empty list. Offset paginated, with a total up front. Filters compose with AND: `report_id` (repeat for several), `scheduled_report_id`, `platform` (repeat for several engines), `date_from`, `date_to` and `category`.","operationId":"list_author_pages_v1_brands__brand_id__citations_authors__author_key__pages_get","parameters":[{"name":"author_key","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":300,"description":"An author's `author_key`.","title":"Author Key"},"description":"An author's `author_key`."},{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Pages per call (1-100, default 20).","default":20,"title":"Limit"},"description":"Pages per call (1-100, default 20)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Pages to skip.","default":0,"title":"Offset"},"description":"Pages to skip."},{"name":"report_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Only these reports (UUIDs); repeat the parameter for several.","title":"Report Id"},"description":"Only these reports (UUIDs); repeat the parameter for several."},{"name":"report_scope","in":"query","required":false,"schema":{"anyOf":[{"const":"all","type":"string"},{"type":"null"}],"description":"`all` for every completed report of the brand, in place of naming each one; the other filters still apply.","title":"Report Scope"},"description":"`all` for every completed report of the brand, in place of naming each one; the other filters still apply."},{"name":"scheduled_report_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only the runs of this Scheduled Report (UUID).","title":"Scheduled Report Id"},"description":"Only the runs of this Scheduled Report (UUID)."},{"name":"tracker_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":200},{"type":"null"}],"description":"Only the runs of these trackers (a report's `tracker_id`; a scheduled report's id is its tracker's); repeat the parameter for several.","title":"Tracker Id"},"description":"Only the runs of these trackers (a report's `tracker_id`; a scheduled report's id is its tracker's); repeat the parameter for several."},{"name":"market_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":200},{"type":"null"}],"description":"Only the runs in these markets (a report's `market_id`, a region config's `id`); repeat the parameter for several.","title":"Market Id"},"description":"Only the runs in these markets (a report's `market_id`, a region config's `id`); repeat the parameter for several."},{"name":"place","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","minLength":1,"maxLength":300},"maxItems":200},{"type":"null"}],"description":"Only the runs in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake, `australia|emerald|victoria`), across every tracker; repeat the parameter for several.","title":"Place"},"description":"Only the runs in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake, `australia|emerald|victoria`), across every tracker; repeat the parameter for several."},{"name":"scope","in":"query","required":false,"schema":{"anyOf":[{"enum":["default","all"],"type":"string"},{"type":"null"}],"description":"`default` reads what the app opens on (every scheduled report's runs plus the newest one-off reports) and takes no other report, tracker, market or place filter; `all` reads every completed report of the brand.","title":"Scope"},"description":"`default` reads what the app opens on (every scheduled report's runs plus the newest one-off reports) and takes no other report, tracker, market or place filter; `all` reads every completed report of the brand."},{"name":"platform","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"enum":["chatgpt","chatgpt_search","perplexity","ai_overviews","claude","claude_search","gemini","grok","muse"],"type":"string"}},{"type":"null"}],"description":"Only answers from these engines; repeat the parameter for several.","title":"Platform"},"description":"Only answers from these engines; repeat the parameter for several."},{"name":"date_from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only answers from this moment on (ISO-8601).","title":"Date From"},"description":"Only answers from this moment on (ISO-8601)."},{"name":"date_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only answers before this moment, exclusive (ISO-8601); not before `date_from`.","title":"Date To"},"description":"Only answers before this moment, exclusive (ISO-8601); not before `date_from`."},{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","maxLength":200},"maxItems":50},{"type":"null"}],"description":"Only answers to prompts of these categories; repeat the parameter for several.","title":"Category"},"description":"Only answers to prompts of these categories; repeat the parameter for several."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned one author's cited pages","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthorPageList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:citations","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/reports/{report_id}/competitors":{"get":{"tags":["Reports"],"summary":"List a report's competitors","description":"Every business the report's answers named, most mentioned first, read through the brand's competitor registry: an alias counts under its competitor's name and relation. `significant` marks the head of the ranking. `platform` reads one AI platform. A report still running answers what it has so far.","operationId":"list_report_competitors_v1_reports__report_id__competitors_get","parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"string","description":"Report UUID.","title":"Report Id"},"description":"Report UUID."},{"name":"platform","in":"query","required":false,"schema":{"anyOf":[{"enum":["chatgpt","chatgpt_search","perplexity","ai_overviews","claude","claude_search","gemini","grok","muse"],"type":"string"},{"type":"null"}],"description":"Only this AI platform, e.g. `chatgpt`.","title":"Platform"},"description":"Only this AI platform, e.g. `chatgpt`."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned a report's competitors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportCompetitorList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:competitors","x-rankprompt-cost":{"request_units":2,"credits":0}}},"/v1/brands/{brand_id}/tracked-pages":{"get":{"tags":["Citations"],"summary":"List pages tracked in Sources","description":"The pages the brand follows in Sources, any site's, with what the answers did with each under the filters; cited ones first. Offset paginated: the stats are read from the answers at read time. Filters compose with AND: `report_id` (repeat for several), `scheduled_report_id`, `platform` (repeat for several engines), `date_from`, `date_to` and `category`.","operationId":"list_tracked_pages_v1_brands__brand_id__tracked_pages_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Words in the URL or title.","title":"Search"},"description":"Words in the URL or title."},{"name":"sort","in":"query","required":false,"schema":{"enum":["citations","recent","prompts","position","change","trend"],"type":"string","description":"Order of the rows.","default":"citations","title":"Sort"},"description":"Order of the rows."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Pages per call (1-500, default 100).","default":100,"title":"Limit"},"description":"Pages per call (1-500, default 100)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Pages to skip.","default":0,"title":"Offset"},"description":"Pages to skip."},{"name":"report_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Only these reports (UUIDs); repeat the parameter for several.","title":"Report Id"},"description":"Only these reports (UUIDs); repeat the parameter for several."},{"name":"report_scope","in":"query","required":false,"schema":{"anyOf":[{"const":"all","type":"string"},{"type":"null"}],"description":"`all` for every completed report of the brand, in place of naming each one; the other filters still apply.","title":"Report Scope"},"description":"`all` for every completed report of the brand, in place of naming each one; the other filters still apply."},{"name":"scheduled_report_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only the runs of this Scheduled Report (UUID).","title":"Scheduled Report Id"},"description":"Only the runs of this Scheduled Report (UUID)."},{"name":"tracker_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":200},{"type":"null"}],"description":"Only the runs of these trackers (a report's `tracker_id`; a scheduled report's id is its tracker's); repeat the parameter for several.","title":"Tracker Id"},"description":"Only the runs of these trackers (a report's `tracker_id`; a scheduled report's id is its tracker's); repeat the parameter for several."},{"name":"market_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":200},{"type":"null"}],"description":"Only the runs in these markets (a report's `market_id`, a region config's `id`); repeat the parameter for several.","title":"Market Id"},"description":"Only the runs in these markets (a report's `market_id`, a region config's `id`); repeat the parameter for several."},{"name":"place","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","minLength":1,"maxLength":300},"maxItems":200},{"type":"null"}],"description":"Only the runs in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake, `australia|emerald|victoria`), across every tracker; repeat the parameter for several.","title":"Place"},"description":"Only the runs in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake, `australia|emerald|victoria`), across every tracker; repeat the parameter for several."},{"name":"scope","in":"query","required":false,"schema":{"anyOf":[{"enum":["default","all"],"type":"string"},{"type":"null"}],"description":"`default` reads what the app opens on (every scheduled report's runs plus the newest one-off reports) and takes no other report, tracker, market or place filter; `all` reads every completed report of the brand.","title":"Scope"},"description":"`default` reads what the app opens on (every scheduled report's runs plus the newest one-off reports) and takes no other report, tracker, market or place filter; `all` reads every completed report of the brand."},{"name":"platform","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"enum":["chatgpt","chatgpt_search","perplexity","ai_overviews","claude","claude_search","gemini","grok","muse"],"type":"string"}},{"type":"null"}],"description":"Only answers from these engines; repeat the parameter for several.","title":"Platform"},"description":"Only answers from these engines; repeat the parameter for several."},{"name":"date_from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only answers from this moment on (ISO-8601).","title":"Date From"},"description":"Only answers from this moment on (ISO-8601)."},{"name":"date_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only answers before this moment, exclusive (ISO-8601); not before `date_from`.","title":"Date To"},"description":"Only answers before this moment, exclusive (ISO-8601); not before `date_from`."},{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","maxLength":200},"maxItems":50},{"type":"null"}],"description":"Only answers to prompts of these categories; repeat the parameter for several.","title":"Category"},"description":"Only answers to prompts of these categories; repeat the parameter for several."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Returned pages tracked in Sources","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackedPageList"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:citations","x-rankprompt-cost":{"request_units":2,"credits":0}},"post":{"tags":["Citations"],"summary":"Track pages","description":"Follow up to 100 pages in Sources; a page already followed comes back as it is. Requires the brand owner on Starter or with an active API subscription: `403 brand_plan_required` otherwise.","operationId":"track_pages_v1_brands__brand_id__tracked_pages_post","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Required with an API key, else `400 idempotency_key_required`: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with `dry_run=true`."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackPages"}}}},"responses":{"201":{"description":"Track pages","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackedPageCreated"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"422":{"description":"Request body did not match the expected schema","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"body_validation_error","message":"Request body did not match the expected schema"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:citations","x-rankprompt-cost":{"request_units":1,"credits":0}},"delete":{"tags":["Citations"],"summary":"Untrack a page","description":"Stop following a page; its past citations stay. A page the brand does not follow answers `404`.","operationId":"untrack_page_v1_brands__brand_id__tracked_pages_delete","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"url","in":"query","required":true,"schema":{"type":"string","minLength":8,"maxLength":4000,"description":"The page URL as tracked.","title":"Url"},"description":"The page URL as tracked."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Optional. A retry with the same key and body within 24 hours replays the first response."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"204":{"description":"No longer tracked.","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"write:citations","x-rankprompt-cost":{"request_units":1,"credits":0}}},"/v1/brands/{brand_id}/visibility/trends":{"get":{"tags":["Visibility trends"],"summary":"Visibility trends","description":"The brand's visibility over its completed runs, one-off reports and schedules alike: every run of the scope (`runs`, oldest first), the places they ran in (`locations`), the AI platforms they asked (`engines`), a page of the prompts (`data`), each with its visibility per run (`sparkline`) and its `trend` (the newer half of its runs against the older half: `up` or `down` past five points, else `stable`), and the runs that asked other prompts, engines or places than their schedule's run before (`run_changes`): a step at one of them is not a gain or a loss.\n\nThe scope composes with AND: `report_id` (repeat for several, up to 100; every completed report when none), `scheduled_report_id`, `tracker_id`, `market_id` and `place` (each repeatable), `scope`, `platform` (repeat for several engines), `date_from` and `date_to` (by each answer's date). `competitors=true` adds `competitor_race`: the competitors named most in each run, counted in the prompts of `prompt_key` and the places of `location_key` (each repeatable, up to 200; every one when none). On a brand with years of runs the read takes a few seconds and the race several more: narrow it with `scheduled_report_id` or `date_from`.\n\nPrompts page with `limit` (1-500, default 100) and `offset`: they are grouped from the answers at read time, most run first, with a total up front.","operationId":"get_visibility_trends_v1_brands__brand_id__visibility_trends_get","parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","description":"Brand UUID.","title":"Brand Id"},"description":"Brand UUID."},{"name":"report_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":100},{"type":"null"}],"description":"Only these reports; repeat the parameter for several.","title":"Report Id"},"description":"Only these reports; repeat the parameter for several."},{"name":"scheduled_report_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only the runs of this Scheduled Report.","title":"Scheduled Report Id"},"description":"Only the runs of this Scheduled Report."},{"name":"tracker_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":200},{"type":"null"}],"description":"Only the runs of these trackers (a report's `tracker_id`; a scheduled report's id is its tracker's); repeat the parameter for several.","title":"Tracker Id"},"description":"Only the runs of these trackers (a report's `tracker_id`; a scheduled report's id is its tracker's); repeat the parameter for several."},{"name":"market_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":200},{"type":"null"}],"description":"Only the runs in these markets (a report's `market_id`, a region config's `id`); repeat the parameter for several.","title":"Market Id"},"description":"Only the runs in these markets (a report's `market_id`, a region config's `id`); repeat the parameter for several."},{"name":"place","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","minLength":1,"maxLength":300},"maxItems":200},{"type":"null"}],"description":"Only the runs in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake, `australia|emerald|victoria`), across every tracker; repeat the parameter for several.","title":"Place"},"description":"Only the runs in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake, `australia|emerald|victoria`), across every tracker; repeat the parameter for several."},{"name":"scope","in":"query","required":false,"schema":{"anyOf":[{"enum":["default","all"],"type":"string"},{"type":"null"}],"description":"`default` reads what the app opens on (every scheduled report's runs plus the newest one-off reports) and takes no other report, tracker, market or place filter; `all` reads every completed report of the brand.","title":"Scope"},"description":"`default` reads what the app opens on (every scheduled report's runs plus the newest one-off reports) and takes no other report, tracker, market or place filter; `all` reads every completed report of the brand."},{"name":"platform","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"enum":["chatgpt","chatgpt_search","perplexity","ai_overviews","claude","claude_search","gemini","grok","muse"],"type":"string"}},{"type":"null"}],"description":"Only answers from these engines; repeat for several.","title":"Platform"},"description":"Only answers from these engines; repeat for several."},{"name":"date_from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only answers from this moment on (ISO-8601).","title":"Date From"},"description":"Only answers from this moment on (ISO-8601)."},{"name":"date_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only answers before this moment, exclusive (ISO-8601); not before `date_from`.","title":"Date To"},"description":"Only answers before this moment, exclusive (ISO-8601); not before `date_from`."},{"name":"competitors","in":"query","required":false,"schema":{"type":"boolean","description":"`true` adds `competitor_race`. Default `false`.","default":false,"title":"Competitors"},"description":"`true` adds `competitor_race`. Default `false`."},{"name":"prompt_key","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","minLength":1,"maxLength":300},"maxItems":200},{"type":"null"}],"description":"Race only: these prompts (`data[].key`); repeat for several.","title":"Prompt Key"},"description":"Race only: these prompts (`data[].key`); repeat for several."},{"name":"location_key","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","minLength":1,"maxLength":300},"maxItems":200},{"type":"null"}],"description":"Race only: these places (`locations[].key`); repeat for several.","title":"Location Key"},"description":"Race only: these places (`locations[].key`); repeat for several."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Prompts per page (1-500, default 100).","default":100,"title":"Limit"},"description":"Prompts per page (1-500, default 100)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Prompts to skip from the start.","default":0,"title":"Offset"},"description":"Prompts to skip from the start."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[\\x21-\\x7e]{1,255}$","title":"Idempotency-Key"},"description":"Ignored on this method."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Dry Run"},"description":"Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns `200` with a `dry_run` object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns `422`."}],"responses":{"200":{"description":"Visibility trends","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VisibilityTrends"}}},"headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"X-RP-Request-Units":{"description":"Request units consumed by this call.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Used":{"description":"Request units consumed in the current billing period (after this call).","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Limit":{"description":"Request units included in the current billing period's plan.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Remaining":{"description":"Request units remaining in the current billing period.","schema":{"type":"integer","minimum":0}},"X-RP-Quota-Reset":{"description":"Unix timestamp (seconds) when the current quota period ends and the counter resets.","schema":{"type":"integer","format":"int64"}},"Idempotent-Replayed":{"description":"Set to `true` when the response was replayed from a prior request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing or invalid credentials","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"unauthorized","message":"Missing or invalid credentials"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"403":{"description":"You do not have permission to access this resource","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"forbidden","message":"You do not have permission to access this resource"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"429":{"description":"Per-minute rate limit exceeded","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"rate_limit_exceeded","message":"Per-minute rate limit exceeded"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"500":{"description":"An unexpected error occurred","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"internal_error","message":"An unexpected error occurred"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"503":{"description":"Service temporarily unavailable, please retry","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"service_unavailable","message":"Service temporarily unavailable, please retry"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"400":{"description":"Request validation failed","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"validation_error","message":"Request validation failed"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"404":{"description":"Resource not found","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"not_found","message":"Resource not found"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"409":{"description":"Resource conflict","headers":{"X-Correlation-ID":{"description":"Server-generated correlation id for this request.","schema":{"type":"string","format":"uuid"}},"X-RP-Duration-Ms":{"description":"Total server-side handler time in milliseconds.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":{"code":"conflict","message":"Resource conflict"},"request_id":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}}},"x-rankprompt-scope":"read:reports","x-rankprompt-cost":{"request_units":3,"credits":0}}}},"components":{"schemas":{"AccountShare":{"properties":{"object":{"type":"string","const":"share","title":"Object","description":"Always `share`.","default":"share"},"id":{"type":"string","title":"Id"},"share_type":{"type":"string","enum":["report","scheduled","brand","brand_audit","portal","document","article_review"],"title":"Share Type","description":"`report`, `scheduled`, `brand`, `brand_audit`, `portal`, `document` (a client report version) or `article_review`."},"url":{"type":"string","title":"Url","description":"The public link, on the account's own domain when it has one."},"brand_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brand Id"},"brand_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brand Name"},"report_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Report Id"},"scheduled_report_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scheduled Report Id"},"brand_audit_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brand Audit Id"},"brief_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brief Id"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"The client report's or the article's title, or the shared report's or schedule's name."},"version_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Version Number","description":"The client report version it shows."},"review_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Review Status","description":"An article review's status."},"render_state":{"anyOf":[{"type":"string","enum":["waiting","ready","failed"]},{"type":"null"}],"title":"Render State","description":"A client report's PDF: `waiting`, `ready`, `failed`."},"view_count":{"type":"integer","minimum":0.0,"title":"View Count","default":0},"last_viewed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Last Viewed At"},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Expires At"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Created At"},"has_password":{"type":"boolean","title":"Has Password","default":false},"refresh_on_view":{"type":"boolean","title":"Refresh On View","description":"Scheduled and brand links show the latest data when opened.","default":false},"can_manage":{"type":"boolean","title":"Can Manage","description":"The key's creator may change or revoke it: edit access to its brand."}},"additionalProperties":false,"type":"object","required":["id","share_type","url","can_manage"],"title":"AccountShare","description":"A public link to a report, schedule, brand overview, brand audit, client report or article review."},"AccountShareList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/AccountShare"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"True when more items exist past this page. Fetch them with a larger `offset`."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of items matching the query, across all pages."},"limit":{"type":"integer","minimum":1.0,"title":"Limit","description":"Page size that was applied."},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of items skipped before this page."}},"additionalProperties":false,"type":"object","required":["data","has_more","total","limit","offset"],"title":"AccountShareList","description":"A page of the account's links, in the order asked for."},"AccountWebhook":{"properties":{"object":{"type":"string","const":"account_webhook","title":"Object","description":"Always `account_webhook`.","default":"account_webhook"},"id":{"type":"string","title":"Id","description":"`whk_` and 32 hex characters."},"url":{"type":"string","title":"Url"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"events":{"items":{"type":"string","enum":["lead.created","lead.report_ready","lead.report_failed","lead.claimed","prospect.report_ready","prospect.stage_changed"]},"type":"array","title":"Events","description":"`lead.created`, `lead.report_ready`, `lead.report_failed` (with `failure_reason`, an open set), `lead.claimed`, `prospect.report_ready` and `prospect.stage_changed` (with `from`, `to`, `lost_reason` and `report_viewed_at`)."},"is_active":{"type":"boolean","title":"Is Active","description":"False once disabled after repeated failures, or turned off."},"secret_fingerprint":{"type":"string","title":"Secret Fingerprint","description":"Identifies the signing secret without revealing it."},"secret_version":{"type":"integer","title":"Secret Version"},"consecutive_failures":{"type":"integer","title":"Consecutive Failures","default":0},"disabled_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Disabled Reason"},"last_success_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"format":"date-time","title":"Last Success At"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"destination_type":{"type":"string","enum":["generic","slack","discord"],"title":"Destination Type","description":"`generic`, `slack` or `discord`."},"custom_header_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Custom Header Name","description":"A header sent with every delivery."}},"additionalProperties":false,"type":"object","required":["id","url","events","is_active","secret_fingerprint","secret_version","created_at","destination_type"],"title":"AccountWebhook","description":"An endpoint that receives the account's lead and prospect events, signed. Never carries the secret or a header's value."},"AccountWebhookCreate":{"properties":{"url":{"type":"string","maxLength":2048,"title":"Url","description":"An https URL."},"events":{"items":{"type":"string","enum":["lead.created","lead.report_ready","lead.report_failed","lead.claimed","prospect.report_ready","prospect.stage_changed"]},"type":"array","maxItems":6,"minItems":1,"title":"Events","description":"`lead.created`, `lead.report_ready`, `lead.report_failed` (with `failure_reason`, an open set), `lead.claimed`, `prospect.report_ready` and `prospect.stage_changed` (with `from`, `to`, `lost_reason` and `report_viewed_at`)."},"description":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Description"},"destination_type":{"type":"string","enum":["generic","slack","discord"],"title":"Destination Type","description":"`slack` and `discord` take their incoming webhook URL and get a chat message.","default":"generic"},"custom_header":{"anyOf":[{"$ref":"#/components/schemas/CustomHeader"},{"type":"null"}]}},"additionalProperties":false,"type":"object","required":["url","events"],"title":"AccountWebhookCreate","description":"A new https endpoint for the account's lead and prospect events.","example":{"events":["lead.created","lead.report_ready"],"url":"https://hooks.rankprompt.com/leads"}},"AccountWebhookCreated":{"properties":{"object":{"type":"string","const":"account_webhook","title":"Object","description":"Always `account_webhook`.","default":"account_webhook"},"id":{"type":"string","title":"Id","description":"`whk_` and 32 hex characters."},"url":{"type":"string","title":"Url"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"events":{"items":{"type":"string","enum":["lead.created","lead.report_ready","lead.report_failed","lead.claimed","prospect.report_ready","prospect.stage_changed"]},"type":"array","title":"Events","description":"`lead.created`, `lead.report_ready`, `lead.report_failed` (with `failure_reason`, an open set), `lead.claimed`, `prospect.report_ready` and `prospect.stage_changed` (with `from`, `to`, `lost_reason` and `report_viewed_at`)."},"is_active":{"type":"boolean","title":"Is Active","description":"False once disabled after repeated failures, or turned off."},"secret_fingerprint":{"type":"string","title":"Secret Fingerprint","description":"Identifies the signing secret without revealing it."},"secret_version":{"type":"integer","title":"Secret Version"},"consecutive_failures":{"type":"integer","title":"Consecutive Failures","default":0},"disabled_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Disabled Reason"},"last_success_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"format":"date-time","title":"Last Success At"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"destination_type":{"type":"string","enum":["generic","slack","discord"],"title":"Destination Type","description":"`generic`, `slack` or `discord`."},"custom_header_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Custom Header Name","description":"A header sent with every delivery."},"secret":{"type":"string","title":"Secret","description":"The signing secret; store it, it is never shown again."}},"additionalProperties":false,"type":"object","required":["id","url","events","is_active","secret_fingerprint","secret_version","created_at","destination_type","secret"],"title":"AccountWebhookCreated","description":"The new endpoint with its signing secret, shown only now."},"AccountWebhookList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/AccountWebhook"},"type":"array","title":"Data"}},"additionalProperties":false,"type":"object","required":["data"],"title":"AccountWebhookList","description":"Every account endpoint, newest first."},"AdsAttributedEvent":{"properties":{"event_name":{"type":"string","title":"Event Name","description":"The event, e.g. `order_created`, or a custom event's name."},"event_kind":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Event Kind","description":"`standard` or `custom`."},"count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Count","description":"Attributed events of this name."},"click_through_conversions":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Click Through Conversions","description":"Of them, after a click."},"view_through_conversions":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"View Through Conversions","description":"Of them, after a view only."},"value_micros":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Value Micros","description":"Their value in micros of `value_currency`; null when they carried none."},"value_currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Value Currency","description":"ISO 4217 code of the value."}},"additionalProperties":false,"type":"object","required":["event_name"],"title":"AdsAttributedEvent","description":"One event's attributed activity under a conversion row, goal and non-goal events alike.","example":{"click_through_conversions":40,"count":52,"event_kind":"standard","event_name":"order_created","value_currency":"USD","value_micros":5912000000,"view_through_conversions":12}},"AdsAttribution":{"properties":{"attribution_window_days":{"type":"integer","enum":[7,14,30],"title":"Attribution Window Days","description":"Days after a click a conversion still counts."},"view_through_attribution_window_days":{"type":"integer","enum":[0,1],"title":"View Through Attribution Window Days","description":"Days after an ad was only seen a conversion still counts; 0 leaves views out."},"attribution_time_basis":{"type":"string","enum":["ad_event_time","conversion_time"],"title":"Attribution Time Basis","description":"`ad_event_time` files a conversion on the day of the click or view, `conversion_time` on its own day."}},"additionalProperties":false,"type":"object","required":["attribution_window_days","view_through_attribution_window_days","attribution_time_basis"],"title":"AdsAttribution","description":"The attribution settings every conversion number in the response was counted with.","example":{"attribution_time_basis":"ad_event_time","attribution_window_days":30,"view_through_attribution_window_days":1}},"AdsCampaign":{"properties":{"object":{"type":"string","const":"openai_ads_campaign","title":"Object","default":"openai_ads_campaign"},"id":{"type":"string","title":"Id","description":"OpenAI's campaign id."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"The campaign's name."},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status","description":"`active`, `paused`, `archived` or `ended`; the set is open."},"bidding_type":{"type":"string","title":"Bidding Type","description":"What the campaign bids for: `impressions`, `clicks` or `conversions`; the set is open."},"objective":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Objective","description":"OpenAI's goal field, e.g. `reach`, `clicks`."},"billing_event_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Billing Event Type","description":"What it pays for: `impression` or `click`."},"mode":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mode","description":"`product_feed` or `business_agent`; null for a standard one."},"daily_budget_micros":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Daily Budget Micros","description":"Daily spend limit. In micros of `currency`: 1,000,000 is one unit."},"lifetime_budget_micros":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Lifetime Budget Micros","description":"Lifetime spend limit. In micros of `currency`: 1,000,000 is one unit."},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency","description":"ISO 4217 code of the ad account."},"start_time":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Start Time","description":"When it starts delivering; null when it has no start."},"end_time":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"End Time","description":"When it stops; null when it runs until paused."},"serving_issues":{"items":{"$ref":"#/components/schemas/AdsServingIssue"},"type":"array","title":"Serving Issues","description":"Why it is not delivering or delivers less; empty when nothing stands in the way."},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Created At","description":"When it was created."},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Updated At","description":"When it last changed."}},"additionalProperties":false,"type":"object","required":["id","status","bidding_type","serving_issues"],"title":"AdsCampaign","description":"One OpenAI Ads campaign: status, budget, bidding and anything keeping it from delivering.","example":{"bidding_type":"conversions","billing_event_type":"click","created_at":"2026-08-28T14:02:11Z","currency":"USD","daily_budget_micros":150000000,"id":"cmp_8f2a1c","name":"Running shoes, US","object":"openai_ads_campaign","objective":"conversions","serving_issues":[{"code":"partial_serving_low_budget","message":"Budget limits delivery.","partial":true}],"start_time":"2026-09-01T00:00:00Z","status":"active","updated_at":"2026-10-02T09:40:00Z"}},"AdsCampaignList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/AdsCampaign"},"type":"array","title":"Data"}},"additionalProperties":false,"type":"object","required":["data"],"title":"AdsCampaignList","description":"Every campaign of the brand's ad account (not paginated).","example":{"data":[{"bidding_type":"conversions","billing_event_type":"click","created_at":"2026-08-28T14:02:11Z","currency":"USD","daily_budget_micros":150000000,"id":"cmp_8f2a1c","name":"Running shoes, US","object":"openai_ads_campaign","objective":"conversions","serving_issues":[{"code":"partial_serving_low_budget","message":"Budget limits delivery.","partial":true}],"start_time":"2026-09-01T00:00:00Z","status":"active","updated_at":"2026-10-02T09:40:00Z"}],"object":"list"}},"AdsConversionRow":{"properties":{"object":{"type":"string","const":"openai_ads_conversion_row","title":"Object","default":"openai_ads_conversion_row"},"entity_type":{"type":"string","enum":["ad_account","campaign","ad_group","ad"],"title":"Entity Type","description":"What the row stands for: the `group_by` of the request."},"entity_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Id","description":"The campaign, ad group or ad; null for the account."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Its name in OpenAI Ads Manager."},"date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Date","description":"The day (YYYY-MM-DD) with granularity `daily`."},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country","description":"With breakdown `country`, where the conversions came from."},"device":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Device","description":"With breakdown `device`, the device they came from."},"conversions":{"type":"integer","title":"Conversions","description":"Click-through plus view-through conversions within the windows."},"click_through_conversions":{"type":"integer","title":"Click Through Conversions","description":"Conversions after a click, the ones billing counts."},"view_through_conversions":{"type":"integer","title":"View Through Conversions","description":"Conversions after the ad was only seen."},"attributed_sales_micros":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Attributed Sales Micros","description":"Value of the attributed purchases, in micros of `attributed_sales_currency`; null when no purchase carried a value, which is not zero."},"attributed_sales_currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Attributed Sales Currency","description":"ISO 4217 code of the sales."},"events":{"anyOf":[{"items":{"$ref":"#/components/schemas/AdsAttributedEvent"},"type":"array"},{"type":"null"}],"title":"Events","description":"Per event, with `include_events=true`; null otherwise."}},"additionalProperties":false,"type":"object","required":["entity_type","conversions","click_through_conversions","view_through_conversions"],"title":"AdsConversionRow","description":"Conversions OpenAI attributed to one entity, or to one entity on one day, country or device.","example":{"attributed_sales_currency":"USD","attributed_sales_micros":5912000000,"click_through_conversions":47,"conversions":61,"entity_id":"cmp_8f2a1c","entity_type":"campaign","events":[{"click_through_conversions":40,"count":52,"event_kind":"standard","event_name":"order_created","value_currency":"USD","value_micros":5912000000,"view_through_conversions":12}],"name":"Running shoes, US","object":"openai_ads_conversion_row","view_through_conversions":14}},"AdsConversionTotals":{"properties":{"conversions":{"type":"integer","title":"Conversions","description":"Click-through plus view-through conversions."},"click_through_conversions":{"type":"integer","title":"Click Through Conversions","description":"Conversions after a click."},"view_through_conversions":{"type":"integer","title":"View Through Conversions","description":"Conversions after a view only."},"attributed_sales_micros":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Attributed Sales Micros","description":"Attributed purchase value in micros of `attributed_sales_currency`; null when none had a value."},"attributed_sales_currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Attributed Sales Currency","description":"ISO 4217 code of the sales."}},"additionalProperties":false,"type":"object","required":["conversions","click_through_conversions","view_through_conversions"],"title":"AdsConversionTotals","description":"Every row summed.","example":{"attributed_sales_currency":"USD","attributed_sales_micros":5912000000,"click_through_conversions":47,"conversions":61,"view_through_conversions":14}},"AdsConversions":{"properties":{"object":{"type":"string","const":"openai_ads_conversions","title":"Object","default":"openai_ads_conversions"},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency","description":"ISO 4217 code of the ad account."},"start_date":{"type":"string","title":"Start Date","description":"First day read (YYYY-MM-DD)."},"end_date":{"type":"string","title":"End Date","description":"Last day read (YYYY-MM-DD); never later than yesterday in UTC."},"group_by":{"type":"string","enum":["ad_account","campaign","ad_group","ad"],"title":"Group By","description":"What each row stands for."},"granularity":{"type":"string","enum":["none","daily"],"title":"Granularity","description":"`none` totals the window; `daily` splits it."},"breakdown":{"anyOf":[{"type":"string","enum":["country","device"]},{"type":"null"}],"title":"Breakdown","description":"The extra split asked for, if any."},"attribution":{"$ref":"#/components/schemas/AdsAttribution"},"data":{"items":{"$ref":"#/components/schemas/AdsConversionRow"},"type":"array","title":"Data","description":"Every row; the report is not paginated."},"totals":{"$ref":"#/components/schemas/AdsConversionTotals"}},"additionalProperties":false,"type":"object","required":["start_date","end_date","group_by","granularity","attribution","data","totals"],"title":"AdsConversions","description":"Attributed conversions for a window, per entity, with every row summed.","example":{"attribution":{"attribution_time_basis":"ad_event_time","attribution_window_days":30,"view_through_attribution_window_days":1},"currency":"USD","data":[{"attributed_sales_currency":"USD","attributed_sales_micros":5912000000,"click_through_conversions":47,"conversions":61,"entity_id":"cmp_8f2a1c","entity_type":"campaign","events":[{"click_through_conversions":40,"count":52,"event_kind":"standard","event_name":"order_created","value_currency":"USD","value_micros":5912000000,"view_through_conversions":12}],"name":"Running shoes, US","object":"openai_ads_conversion_row","view_through_conversions":14}],"end_date":"2026-10-15","granularity":"none","group_by":"campaign","object":"openai_ads_conversions","start_date":"2026-09-18","totals":{"attributed_sales_currency":"USD","attributed_sales_micros":5912000000,"click_through_conversions":47,"conversions":61,"view_through_conversions":14}}},"AdsPerformance":{"properties":{"object":{"type":"string","const":"openai_ads_performance","title":"Object","default":"openai_ads_performance"},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency","description":"ISO 4217 code of the ad account, which money is in."},"start_date":{"type":"string","title":"Start Date","description":"First day read (YYYY-MM-DD)."},"end_date":{"type":"string","title":"End Date","description":"Last day read (YYYY-MM-DD); never later than yesterday in UTC."},"level":{"type":"string","enum":["ad_account","campaign","ad_group","ad"],"title":"Level","description":"The scope read: the whole account or one entity."},"entity_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Id","description":"The campaign, ad group or ad read; null for the account."},"group_by":{"type":"string","enum":["ad_account","campaign","ad_group","ad"],"title":"Group By","description":"What each row stands for."},"granularity":{"type":"string","enum":["none","daily","monthly"],"title":"Granularity","description":"`none` totals the window; `daily` and `monthly` split it."},"attribution":{"$ref":"#/components/schemas/AdsAttribution"},"data":{"items":{"$ref":"#/components/schemas/AdsPerformanceRow"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"True when another page follows; pass `next_cursor` as `cursor` to read it."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Opaque cursor for the next page; null on the last."}},"additionalProperties":false,"type":"object","required":["start_date","end_date","level","group_by","granularity","attribution","data","has_more"],"title":"AdsPerformance","description":"OpenAI Ads performance for a window: one row per entity, or per entity and day or month.","example":{"attribution":{"attribution_time_basis":"ad_event_time","attribution_window_days":30,"view_through_attribution_window_days":1},"currency":"USD","data":[{"attributed_sales_currency":"USD","attributed_sales_micros":5912000000,"clicks":912,"conversions":61,"cpa_micros":21057377,"cpc_micros":1408442,"cpm_micros":26643850,"ctr":0.018917,"entity_id":"cmp_8f2a1c","entity_type":"campaign","impressions":48210,"name":"Running shoes, US","object":"openai_ads_performance_row","roas":4.6,"spend_micros":1284500000}],"end_date":"2026-10-15","granularity":"none","group_by":"campaign","has_more":false,"level":"ad_account","object":"openai_ads_performance","start_date":"2026-09-18"}},"AdsPerformanceRow":{"properties":{"object":{"type":"string","const":"openai_ads_performance_row","title":"Object","default":"openai_ads_performance_row"},"entity_type":{"type":"string","enum":["ad_account","campaign","ad_group","ad"],"title":"Entity Type","description":"What the row stands for: the `group_by` of the request."},"entity_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Id","description":"OpenAI's id of the account, campaign, ad group or ad."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Its name in OpenAI Ads Manager."},"date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Date","description":"The day or month the row covers, as OpenAI labels it; null with granularity `none`."},"impressions":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Impressions","description":"Times the ad was shown."},"clicks":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Clicks","description":"Clicks on the ad."},"spend_micros":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Spend Micros","description":"Amount spent. In micros of `currency`: 1,000,000 is one unit."},"ctr":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ctr","description":"Clicks over impressions, as a fraction from 0 to 1."},"cpc_micros":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cpc Micros","description":"Average cost per click. In micros of `currency`: 1,000,000 is one unit."},"cpm_micros":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cpm Micros","description":"Average cost per thousand impressions. In micros of `currency`: 1,000,000 is one unit."},"conversions":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Conversions","description":"Click-through plus view-through conversions within the attribution windows."},"cpa_micros":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cpa Micros","description":"Spend over every conversion, click-through plus view-through, as Ads Manager reports it; null when there were none, never zero. In micros of `currency`: 1,000,000 is one unit."},"attributed_sales_micros":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Attributed Sales Micros","description":"Value of the attributed purchases, in micros of `attributed_sales_currency`; null when no purchase carried a value, which is not zero."},"attributed_sales_currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Attributed Sales Currency","description":"ISO 4217 code of the sales."},"roas":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Roas","description":"Attributed sales over spend, as a ratio (4.6 is 460%)."}},"additionalProperties":false,"type":"object","required":["entity_type"],"title":"AdsPerformanceRow","description":"Delivery and conversion metrics for one entity, or one entity on one day or month.","example":{"attributed_sales_currency":"USD","attributed_sales_micros":5912000000,"clicks":912,"conversions":61,"cpa_micros":21057377,"cpc_micros":1408442,"cpm_micros":26643850,"ctr":0.018917,"entity_id":"cmp_8f2a1c","entity_type":"campaign","impressions":48210,"name":"Running shoes, US","object":"openai_ads_performance_row","roas":4.6,"spend_micros":1284500000}},"AdsServingIssue":{"properties":{"code":{"type":"string","title":"Code","description":"OpenAI's code for the issue; the set is open and grows."},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message","description":"OpenAI's explanation."},"partial":{"type":"boolean","title":"Partial","description":"True when the campaign still delivers, only less."}},"additionalProperties":false,"type":"object","required":["code","partial"],"title":"AdsServingIssue","description":"One reason a campaign is not delivering, or delivering less."},"AgencyReview":{"properties":{"object":{"type":"string","const":"agency_review","title":"Object","default":"agency_review"},"review_id":{"type":"string","title":"Review Id"},"brand_id":{"type":"string","title":"Brand Id"},"brand_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brand Name"},"brief_id":{"type":"string","title":"Brief Id"},"article_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Article Title"},"status":{"type":"string","title":"Status"},"reviewer_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reviewer Name"},"version":{"type":"integer","title":"Version","default":1},"unresolved_comments":{"type":"integer","title":"Unresolved Comments","default":0},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expires At"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated At","description":"When it last moved: how long it has waited."}},"additionalProperties":false,"type":"object","required":["review_id","brand_id","brief_id","status"],"title":"AgencyReview","description":"An article review waiting on someone."},"AgencyReviewList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/AgencyReview"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"True when more items exist past this page. Fetch them with a larger `offset`."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of items matching the query, across all pages."},"limit":{"type":"integer","minimum":1.0,"title":"Limit","description":"Page size that was applied."},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of items skipped before this page."}},"additionalProperties":false,"type":"object","required":["data","has_more","total","limit","offset"],"title":"AgencyReviewList","description":"A page of the reviews waiting, oldest first."},"AgencyTask":{"properties":{"object":{"type":"string","const":"agency_task","title":"Object","default":"agency_task"},"id":{"type":"string","title":"Id"},"brand_id":{"type":"string","title":"Brand Id"},"brand_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brand Name"},"title":{"type":"string","title":"Title"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"status":{"type":"string","title":"Status","description":"`suggested`, `backlog`, `in_progress`, `review`, `approved`, `done`, `dismissed`."},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category"},"priority":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Priority"},"source_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Type"},"brief_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brief Id"},"report_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Report Id"},"content_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content Type"},"effort_level":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Effort Level"},"estimated_impact":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Estimated Impact"},"action_items":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Action Items"},"assignee_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Assignee Id"},"external_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Url"},"due_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Due Date"},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completed At"},"archived_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Archived At"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated At"}},"additionalProperties":false,"type":"object","required":["id","brand_id","title","status"],"title":"AgencyTask","description":"A task of any brand of the portfolio."},"AgencyTaskList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/AgencyTask"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"True when more items exist past this page. Fetch them with a larger `offset`."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of items matching the query, across all pages."},"limit":{"type":"integer","minimum":1.0,"title":"Limit","description":"Page size that was applied."},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of items skipped before this page."}},"additionalProperties":false,"type":"object","required":["data","has_more","total","limit","offset"],"title":"AgencyTaskList","description":"A page of the portfolio's tasks."},"AgencyTaskSummary":{"properties":{"object":{"type":"string","const":"agency_task_summary","title":"Object","default":"agency_task_summary"},"by_status":{"additionalProperties":{"type":"integer"},"type":"object","title":"By Status"},"by_priority":{"additionalProperties":{"type":"integer"},"type":"object","title":"By Priority"}},"additionalProperties":false,"type":"object","required":["by_status","by_priority"],"title":"AgencyTaskSummary","description":"Task counts across the portfolio, by status and priority; archived tasks are left out."},"AiCrawlerActivity":{"properties":{"object":{"type":"string","const":"ai_crawler_activity","title":"Object","default":"ai_crawler_activity"},"days":{"type":"integer","title":"Days","description":"Length of the window in days, today included."},"date_from":{"type":"string","title":"Date From","description":"First day of the window (YYYY-MM-DD)."},"date_to":{"type":"string","title":"Date To","description":"Last day of the window (YYYY-MM-DD), today."},"pages_crawled":{"type":"integer","title":"Pages Crawled","description":"Distinct paths any crawler fetched in the window."},"sources":{"items":{"$ref":"#/components/schemas/AiCrawlerSource"},"type":"array","title":"Sources","description":"The brand's log sources. Empty when none is connected: then an empty `bots` means no logs, not no crawler visits."},"bots":{"items":{"$ref":"#/components/schemas/AiCrawlerBot"},"type":"array","title":"Bots","description":"One row per crawler seen in the window, most requests first. Empty until a source sends logs."}},"additionalProperties":false,"type":"object","required":["days","date_from","date_to","pages_crawled","sources","bots"],"title":"AiCrawlerActivity","description":"The brand's AI crawler visits over a window of days, one row per crawler, most requests first.","example":{"bots":[{"bot_id":"oai-searchbot","engine":"chatgpt","error_hits":6,"hits":412,"last_seen_at":"2026-10-17T08:12:44+00:00","name":"OAI-SearchBot","operator":"OpenAI","pages":61,"purpose":"search","verified_hits":398}],"date_from":"2026-09-18","date_to":"2026-10-17","days":30,"object":"ai_crawler_activity","pages_crawled":84,"sources":[{"hosts":["rankprompt.com","www.rankprompt.com"],"kind":"cloudflare","last_received_at":"2026-10-17T09:00:00+00:00","status":"active"}]}},"AiCrawlerBot":{"properties":{"bot_id":{"type":"string","title":"Bot Id","description":"Stable id of the crawler, e.g. `gptbot` or `oai-searchbot`."},"name":{"type":"string","title":"Name","description":"The crawler's user agent name, e.g. `GPTBot`."},"operator":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Operator","description":"The company that runs it, e.g. `OpenAI`."},"purpose":{"anyOf":[{"type":"string","enum":["training","search","user","ads"]},{"type":"null"}],"title":"Purpose","description":"What it fetches for: `training`, `search` (an answer engine's index), `user` (a fetch on a user's request) or `ads`."},"engine":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Engine","description":"The tracked AI platform it feeds, e.g. `chatgpt`, or null. An open set: a new value may appear."},"hits":{"type":"integer","title":"Hits","description":"Requests in the window."},"verified_hits":{"type":"integer","title":"Verified Hits","description":"Requests from the operator's published addresses; the rest may be scrapers using its name."},"error_hits":{"type":"integer","title":"Error Hits","description":"Requests answered with a 4xx or 5xx status."},"pages":{"type":"integer","title":"Pages","description":"Distinct paths it fetched."},"last_seen_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Last Seen At","description":"Its latest request in the window."}},"additionalProperties":false,"type":"object","required":["bot_id","name","hits","verified_hits","error_hits","pages"],"title":"AiCrawlerBot","description":"One crawler over the window."},"AiCrawlerSource":{"properties":{"kind":{"type":"string","enum":["upload","cloudflare","wordpress","worker","vercel"],"title":"Kind","description":"Where the logs come from: an uploaded access log, Cloudflare, the WordPress connector plugin, a Cloudflare Worker or a Vercel log drain."},"status":{"type":"string","enum":["active","paused","error"],"title":"Status","description":"`active` reads or receives logs, `paused` stopped (see `paused_reason`), `error` failed its last read (see `last_error_code`)."},"paused_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Paused Reason","description":"Why a paused source stopped."},"hosts":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Hosts","description":"The hosts it reads (a Cloudflare zone's chosen hosts, a Vercel project's domains); null when it takes every host its logs carry."},"last_received_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Last Received At","description":"When it last delivered logs; null when it never has."},"last_error_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Error Code","description":"Its last read's error, when that read failed."},"last_error_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Last Error At","description":"When that error happened."}},"additionalProperties":false,"type":"object","required":["kind","status"],"title":"AiCrawlerSource","description":"A source that sends the brand's crawler logs."},"AiGeoAnswer":{"properties":{"prompt":{"type":"string","title":"Prompt"},"status":{"type":"string","enum":["answered","failed"],"title":"Status"},"brand_appears":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Brand Appears"},"brand_rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Brand Rank","description":"The brand's position among the businesses named."},"businesses":{"items":{"$ref":"#/components/schemas/AiGeoBusiness"},"type":"array","title":"Businesses"},"citations":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Citations","description":"The answer's sources. A Google Maps place has `provider_metadata.grounding` `google_maps`; show it with its name, its link and the words Google Maps, untranslated."},"model_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model Version"}},"additionalProperties":false,"type":"object","required":["prompt","status","businesses","citations"],"title":"AiGeoAnswer"},"AiGeoBusiness":{"properties":{"name":{"type":"string","title":"Name"},"rank":{"type":"integer","title":"Rank","description":"Its position in the answer, 1 first."},"place_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Place Id","description":"Its Google place id when Google Maps grounded it."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"Its Google Maps link."},"is_brand":{"type":"boolean","title":"Is Brand"}},"additionalProperties":false,"type":"object","required":["name","rank","is_brand"],"title":"AiGeoBusiness"},"AiGeoLocalPack":{"properties":{"geo_scan_id":{"type":"string","title":"Geo Scan Id"},"keyword":{"type":"string","title":"Keyword"},"scanned_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scanned At"},"distance_km":{"type":"number","title":"Distance Km","description":"How far the Maps point sits from this point."},"rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rank","description":"The place's rank in the local pack there."},"local_pack":{"items":{"$ref":"#/components/schemas/GeoScanCompetitor"},"type":"array","title":"Local Pack"}},"additionalProperties":false,"type":"object","required":["geo_scan_id","keyword","distance_km","local_pack"],"title":"AiGeoLocalPack"},"AiGeoPoint":{"properties":{"object":{"type":"string","const":"ai_geo_point","title":"Object","description":"Always `ai_geo_point`.","default":"ai_geo_point"},"point":{"$ref":"#/components/schemas/AiGeoScanPoint"},"answers":{"items":{"$ref":"#/components/schemas/AiGeoAnswer"},"type":"array","title":"Answers"},"local_pack":{"anyOf":[{"$ref":"#/components/schemas/AiGeoLocalPack"},{"type":"null"}],"description":"Null when the place has no completed Maps scan with a point near this one."}},"additionalProperties":false,"type":"object","required":["point","answers"],"title":"AiGeoPoint","description":"A point of an AI grid: every prompt's answer and the Google Maps local pack at the same spot."},"AiGeoScan":{"properties":{"object":{"type":"string","const":"ai_geo_scan","title":"Object","description":"Always `ai_geo_scan`.","default":"ai_geo_scan"},"id":{"type":"string","title":"Id"},"location_id":{"type":"string","title":"Location Id","description":"The place the grid is centred on."},"run_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run Id","description":"The local scan it is part of: its Maps scans share it. Null on an AI grid alone."},"schedule_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Schedule Id","description":"The schedule that ran it; null for a scan by hand."},"grid_size":{"type":"integer","title":"Grid Size"},"spacing_km":{"type":"number","title":"Spacing Km"},"center_lat":{"type":"number","title":"Center Lat"},"center_lng":{"type":"number","title":"Center Lng"},"prompts":{"items":{"type":"string"},"type":"array","title":"Prompts"},"point_count":{"type":"integer","title":"Point Count"},"cells_total":{"type":"integer","title":"Cells Total","description":"Points times prompts: one Gemini answer each."},"cells_answered":{"type":"integer","title":"Cells Answered"},"cells_failed":{"type":"integer","title":"Cells Failed"},"status":{"type":"string","enum":["pending","running","completed","failed"],"title":"Status","description":"`pending`, `running`, `completed` or `failed`."},"visibility_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Visibility Pct","description":"Share of the answered cells that name the brand, 0 to 100."},"credits_charged":{"type":"integer","title":"Credits Charged","description":"Reserved at the start; once settled, what was kept."},"last_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Error"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completed At"},"points":{"items":{"$ref":"#/components/schemas/AiGeoScanPoint"},"type":"array","title":"Points"}},"additionalProperties":false,"type":"object","required":["id","location_id","grid_size","spacing_km","center_lat","center_lng","prompts","point_count","cells_total","cells_answered","cells_failed","status","credits_charged"],"title":"AiGeoScan","description":"An AI grid scan with every point of its grid."},"AiGeoScanBusiness":{"properties":{"object":{"type":"string","const":"ai_geo_business","title":"Object","description":"Always `ai_geo_business`.","default":"ai_geo_business"},"name":{"type":"string","title":"Name"},"place_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Place Id"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"},"is_brand":{"type":"boolean","title":"Is Brand"},"cells":{"type":"integer","title":"Cells","description":"Answers that named it."},"points":{"type":"integer","title":"Points","description":"Grid points where an answer named it."},"avg_rank":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Rank"},"first_count":{"type":"integer","title":"First Count","description":"Answers that named it first."}},"additionalProperties":false,"type":"object","required":["name","is_brand","cells","points","first_count"],"title":"AiGeoScanBusiness"},"AiGeoScanBusinessList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/AiGeoScanBusiness"},"type":"array","title":"Data"}},"additionalProperties":false,"type":"object","required":["data"],"title":"AiGeoScanBusinessList","description":"The businesses the scan's answers named most, up to 20."},"AiGeoScanCreate":{"properties":{"grid_size":{"type":"integer","title":"Grid Size","description":"N in the NxN grid (3, 5 or 7)","default":3},"spacing_km":{"type":"number","maximum":20.0,"exclusiveMinimum":0.0,"title":"Spacing Km","description":"Distance between adjacent grid points","default":1.5},"center_lat":{"anyOf":[{"type":"number","maximum":90.0,"minimum":-90.0},{"type":"null"}],"title":"Center Lat","description":"The grid's centre; null uses the place's pin"},"center_lng":{"anyOf":[{"type":"number","maximum":180.0,"minimum":-180.0},{"type":"null"}],"title":"Center Lng"},"prompts":{"items":{"type":"string"},"type":"array","maxItems":5,"minItems":1,"title":"Prompts","description":"Prompts as a customer would ask them, without the city (\"near me\" is fine): the point is the place."}},"additionalProperties":false,"type":"object","required":["prompts"],"title":"AiGeoScanCreate","description":"Ask Gemini every prompt at every point of a grid around the place.","example":{"grid_size":3,"prompts":["best dentist near me"],"spacing_km":1.5}},"AiGeoScanList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/AiGeoScanSummary"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Opaque continuation token. Pass back as `?cursor=` to fetch the next page. `null` when `has_more` is false."}},"additionalProperties":false,"type":"object","required":["data","has_more"],"title":"AiGeoScanList","description":"A page of a place's AI grid scans, newest first."},"AiGeoScanPoint":{"properties":{"id":{"type":"string","title":"Id"},"grid_row":{"type":"integer","title":"Grid Row","description":"0 is the northern row."},"grid_col":{"type":"integer","title":"Grid Col","description":"0 is the western column."},"lat":{"type":"number","title":"Lat"},"lng":{"type":"number","title":"Lng"},"label":{"type":"string","title":"Label","description":"Where the point sits from the centre, such as \"1.5 km N, 1.5 km W\" or \"centre\"."},"visibility_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Visibility Pct","description":"Share of the point's answered prompts that name the brand, 0 to 100."}},"additionalProperties":false,"type":"object","required":["id","grid_row","grid_col","lat","lng","label"],"title":"AiGeoScanPoint"},"AiGeoScanSummary":{"properties":{"object":{"type":"string","const":"ai_geo_scan","title":"Object","description":"Always `ai_geo_scan`.","default":"ai_geo_scan"},"id":{"type":"string","title":"Id"},"location_id":{"type":"string","title":"Location Id","description":"The place the grid is centred on."},"run_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run Id","description":"The local scan it is part of: its Maps scans share it. Null on an AI grid alone."},"schedule_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Schedule Id","description":"The schedule that ran it; null for a scan by hand."},"grid_size":{"type":"integer","title":"Grid Size"},"spacing_km":{"type":"number","title":"Spacing Km"},"center_lat":{"type":"number","title":"Center Lat"},"center_lng":{"type":"number","title":"Center Lng"},"prompts":{"items":{"type":"string"},"type":"array","title":"Prompts"},"point_count":{"type":"integer","title":"Point Count"},"cells_total":{"type":"integer","title":"Cells Total","description":"Points times prompts: one Gemini answer each."},"cells_answered":{"type":"integer","title":"Cells Answered"},"cells_failed":{"type":"integer","title":"Cells Failed"},"status":{"type":"string","enum":["pending","running","completed","failed"],"title":"Status","description":"`pending`, `running`, `completed` or `failed`."},"visibility_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Visibility Pct","description":"Share of the answered cells that name the brand, 0 to 100."},"credits_charged":{"type":"integer","title":"Credits Charged","description":"Reserved at the start; once settled, what was kept."},"last_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Error"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completed At"}},"additionalProperties":false,"type":"object","required":["id","location_id","grid_size","spacing_km","center_lat","center_lng","prompts","point_count","cells_total","cells_answered","cells_failed","status","credits_charged"],"title":"AiGeoScanSummary","description":"An AI grid scan of a place without its points."},"AiLandingPage":{"properties":{"object":{"type":"string","const":"ai_landing_page","title":"Object","default":"ai_landing_page"},"engine":{"type":"string","title":"Engine"},"path":{"type":"string","title":"Path","description":"Landing page path."},"sessions":{"type":"integer","minimum":0.0,"title":"Sessions","default":0},"users":{"type":"integer","minimum":0.0,"title":"Users","default":0},"page_views":{"type":"integer","minimum":0.0,"title":"Page Views","default":0},"engagement_rate":{"type":"number","title":"Engagement Rate","description":"GA4 engagement rate, as a percentage.","default":0.0},"key_events":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Key Events","description":"GA4 key events from these visits; null when the window was read before they were."},"revenue":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Revenue","description":"GA4 totalRevenue from these visits, in `currency_code` of the traffic block."}},"additionalProperties":false,"type":"object","required":["engine","path"],"title":"AiLandingPage","description":"A page the answer engines send people to."},"AiSuggestionRequest":{"properties":{"force_regenerate":{"type":"boolean","title":"Force Regenerate","description":"Regenerate from scratch even when a cached suggestion exists (debits a fresh credit).","default":false}},"additionalProperties":false,"type":"object","title":"AiSuggestionRequest","description":"Request body for generating a report's AI suggestion."},"AiSuggestionResult":{"properties":{"object":{"type":"string","const":"ai_suggestion","title":"Object","description":"Always `ai_suggestion`.","default":"ai_suggestion"},"ai_suggestion":{"type":"string","title":"Ai Suggestion","description":"The generated suggestion narrative."},"tasks_created":{"type":"integer","minimum":0.0,"title":"Tasks Created","description":"Number of tasks persisted from this suggestion."},"tasks":{"items":{"$ref":"#/components/schemas/Task"},"type":"array","title":"Tasks","description":"Tasks created (or cached) from the suggestion."},"analysis":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Analysis","description":"Structured analysis backing the suggestion, when available."}},"additionalProperties":false,"type":"object","required":["ai_suggestion","tasks_created"],"title":"AiSuggestionResult","description":"An AI suggestion plus the tasks it created for the brand.","example":{"ai_suggestion":"Your brand trails on comparison queries. Ship a head-to-head page ...","object":"ai_suggestion","tasks":[],"tasks_created":2}},"AiTraffic":{"properties":{"object":{"type":"string","const":"ai_traffic","title":"Object","default":"ai_traffic"},"sessions":{"type":"integer","minimum":0.0,"title":"Sessions","description":"Sessions from every answer engine in the window.","default":0},"users":{"type":"integer","minimum":0.0,"title":"Users","default":0},"page_views":{"type":"integer","minimum":0.0,"title":"Page Views","default":0},"key_events":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Key Events","description":"GA4 key events from every answer engine in the window; null when it was read before they were."},"revenue":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Revenue","description":"GA4 totalRevenue from every answer engine in the window."},"currency_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency Code","description":"ISO 4217 currency of the GA4 property, which `revenue` is reported in."},"sources":{"items":{"$ref":"#/components/schemas/AiTrafficSource"},"type":"array","title":"Sources","description":"Split per engine."},"landing_pages":{"items":{"$ref":"#/components/schemas/AiLandingPage"},"type":"array","title":"Landing Pages","description":"Where they landed."},"by_date":{"items":{"$ref":"#/components/schemas/AiTrafficPoint"},"type":"array","title":"By Date"},"date_range_start":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Date Range Start"},"date_range_end":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Date Range End"},"last_sync_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Last Sync At","description":"When Google was last read for this window; null when nothing is stored for it. Refresh when it is null or old."}},"additionalProperties":false,"type":"object","title":"AiTraffic","description":"Visits the answer engines actually sent, the other half of a visibility score."},"AiTrafficPoint":{"properties":{"object":{"type":"string","const":"ai_traffic_point","title":"Object","default":"ai_traffic_point"},"date":{"type":"string","title":"Date"},"engine":{"type":"string","title":"Engine"},"sessions":{"type":"integer","minimum":0.0,"title":"Sessions","default":0},"users":{"type":"integer","minimum":0.0,"title":"Users","default":0},"page_views":{"type":"integer","minimum":0.0,"title":"Page Views","default":0},"key_events":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Key Events","description":"GA4 key events from these visits; null when the window was read before they were."},"revenue":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Revenue","description":"GA4 totalRevenue from these visits, in `currency_code` of the traffic block."}},"additionalProperties":false,"type":"object","required":["date","engine"],"title":"AiTrafficPoint","description":"One engine's AI referral traffic on one day."},"AiTrafficSource":{"properties":{"object":{"type":"string","const":"ai_traffic_source","title":"Object","default":"ai_traffic_source"},"engine":{"type":"string","title":"Engine","description":"The engine, as named by Rank Prompt (e.g. `ChatGPT`, `Perplexity`)."},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source","description":"The raw GA4 source the engine was matched from."},"sessions":{"type":"integer","minimum":0.0,"title":"Sessions","default":0},"users":{"type":"integer","minimum":0.0,"title":"Users","default":0},"page_views":{"type":"integer","minimum":0.0,"title":"Page Views","default":0},"engagement_rate":{"type":"number","title":"Engagement Rate","description":"GA4 engagement rate, as a percentage.","default":0.0},"avg_session_duration":{"type":"number","title":"Avg Session Duration","description":"Average session length, in seconds.","default":0.0},"key_events":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Key Events","description":"GA4 key events from these visits; null when the window was read before they were."},"revenue":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Revenue","description":"GA4 totalRevenue from these visits, in `currency_code` of the traffic block."}},"additionalProperties":false,"type":"object","required":["engine"],"title":"AiTrafficSource","description":"One answer engine sending visits, as GA4 sees its referrals."},"AliasSuggestion":{"properties":{"object":{"type":"string","title":"Object","description":"Always `alias_suggestion`.","default":"alias_suggestion"},"brand_id":{"type":"string","title":"Brand Id","description":"Owning brand id (UUID)."},"business_name":{"type":"string","title":"Business Name","description":"Suggested alias name. Use as path component for accept/dismiss (URL-encode if needed)."},"confidence":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Confidence","description":"0-100 confidence score."},"occurrences":{"type":"integer","minimum":0.0,"title":"Occurrences","description":"Recent answers that mention this business."},"signals":{"items":{"type":"string"},"type":"array","title":"Signals","description":"Matching signals that fired (e.g. `unicode_containment`, `fuzzy_full_match`, `citation_domain_match`)."}},"additionalProperties":false,"type":"object","required":["brand_id","business_name","confidence","occurrences"],"title":"AliasSuggestion","description":"A single pending alias suggestion for a brand.","example":{"brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","business_name":"adidas Running","confidence":87,"object":"alias_suggestion","occurrences":4,"signals":["unicode_containment","fuzzy_full_match"]}},"AliasSuggestionAccepted":{"properties":{"object":{"type":"string","title":"Object","description":"Always `alias_suggestion.accepted`.","default":"alias_suggestion.accepted"},"brand_id":{"type":"string","title":"Brand Id","description":"Owning brand id (UUID)."},"business_name":{"type":"string","title":"Business Name","description":"The accepted suggestion (echoed back)."},"added_alias":{"type":"string","title":"Added Alias","description":"The alias appended to `brands.brand_aliases` (typically equal to `business_name`)."},"brand_aliases":{"items":{"type":"string"},"type":"array","title":"Brand Aliases","description":"The brand's full `brand_aliases` array after the acceptance."},"remaining":{"type":"integer","minimum":0.0,"title":"Remaining","description":"Pending suggestions left after the acceptance."}},"additionalProperties":false,"type":"object","required":["brand_id","business_name","added_alias","brand_aliases","remaining"],"title":"AliasSuggestionAccepted","description":"Acceptance envelope returned after promoting a suggestion to an alias.","example":{"added_alias":"adidas Running","brand_aliases":["adidas Originals","adidas AG","adidas Running"],"brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","business_name":"adidas Running","object":"alias_suggestion.accepted","remaining":3}},"AliasSuggestionList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/AliasSuggestion"},"type":"array","title":"Data"}},"additionalProperties":false,"type":"object","required":["data"],"title":"AliasSuggestionList","description":"Pending alias suggestions for one brand.","example":{"data":[{"brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","business_name":"adidas Running","confidence":87,"object":"alias_suggestion","occurrences":4,"signals":["unicode_containment","fuzzy_full_match"]}],"object":"list"}},"AnalyticsConnection":{"properties":{"object":{"type":"string","const":"analytics_connection","title":"Object","default":"analytics_connection"},"status":{"type":"string","title":"Status","description":"Connection state. One of `connected`, `not_connected`, `expired`, `revoked`, or `error`."},"google_analytics":{"type":"boolean","title":"Google Analytics","description":"True when the GA4 (analytics.readonly) scope is linked."},"search_console":{"type":"boolean","title":"Search Console","description":"True when the Search Console (webmasters.readonly) scope is linked."},"business_profile":{"type":"boolean","title":"Business Profile","description":"True when the Business Profile (business.manage) scope is linked."},"merchant_center":{"type":"boolean","title":"Merchant Center","description":"True when the Merchant Center (content) scope is linked. Read only in practice.","default":false},"youtube":{"type":"boolean","title":"Youtube","description":"True when the YouTube (youtube.readonly) scope is linked.","default":false},"ga4_property_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ga4 Property Id","description":"Selected GA4 property resource name (e.g. `properties/123456789`)."},"gsc_site_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gsc Site Url","description":"Selected Search Console site (e.g. `sc-domain:rankprompt.com`)."},"last_error_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Error Code","description":"Why the connection needs its owner, or null when it works. An open set (new values can appear): `token_expired`, `scope_missing`, `not_selected`, `auth_failed`, `permission_missing`, `site_unreachable`, `host_moved`, `app_uninstalled`, `rate_limited`, `vendor_down`."},"last_error_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Last Error At","description":"When `last_error_code` was set; null while the connection works."}},"additionalProperties":false,"type":"object","required":["status","google_analytics","search_console","business_profile"],"title":"AnalyticsConnection","description":"Status of the brand's stored Google connection and its per-service scopes.","example":{"business_profile":false,"ga4_property_id":"properties/123456789","google_analytics":true,"gsc_site_url":"sc-domain:rankprompt.com","merchant_center":false,"object":"analytics_connection","search_console":true,"status":"connected","youtube":false}},"AnalyticsConnectionLink":{"properties":{"object":{"type":"string","const":"analytics_connection_link","title":"Object","default":"analytics_connection_link"},"url":{"type":"string","title":"Url","description":"The Rank Prompt page that starts Google consent. The user opens it signed in to Rank Prompt."},"already_connected":{"type":"boolean","title":"Already Connected","description":"True when Google is already linked and this link would only re-consent.","default":false}},"additionalProperties":false,"type":"object","required":["url"],"title":"AnalyticsConnectionLink","description":"A link the brand's owner opens once to let Rank Prompt read their Google data."},"AnalyticsConnectionUpdate":{"properties":{"ga4_property_id":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Ga4 Property Id","description":"From `ga4_properties[].property_id`."},"gsc_site_url":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Gsc Site Url","description":"From `gsc_sites[].site_url`."}},"additionalProperties":false,"type":"object","title":"AnalyticsConnectionUpdate","description":"Pick which GA4 property and Search Console site the brand reads."},"AnalyticsRefresh":{"properties":{"object":{"type":"string","const":"analytics_refresh","title":"Object","default":"analytics_refresh"},"refreshed":{"items":{"type":"string","enum":["ga4","search_console"]},"type":"array","title":"Refreshed","description":"Sources that came back."},"errors":{"items":{"type":"string"},"type":"array","title":"Errors","description":"What did not come back, and why."},"already_running":{"type":"boolean","title":"Already Running","description":"Another refresh of this brand was already in flight.","default":false},"date_range_start":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Date Range Start"},"date_range_end":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Date Range End"}},"additionalProperties":false,"type":"object","title":"AnalyticsRefresh","description":"Outcome of pulling the brand's Google data again."},"AnalyticsSummary":{"properties":{"object":{"type":"string","const":"analytics_summary","title":"Object","default":"analytics_summary"},"has_data":{"type":"boolean","title":"Has Data","description":"False while nothing was read from Google yet."},"gsc_site_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gsc Site Url","description":"The Search Console site read."},"ga4_property_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ga4 Property Name","description":"The GA4 property read."},"last_sync_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Last Sync At","description":"When Google was last read."},"date_start":{"type":"string","title":"Date Start","description":"First day of the window (YYYY-MM-DD)."},"date_end":{"type":"string","title":"Date End","description":"Last day of the window (YYYY-MM-DD)."},"top_queries":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Top Queries","description":"Up to 20 Search Console queries with `clicks`, `impressions`, `ctr` and `position`."},"top_pages":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Top Pages","description":"Up to 20 Search Console pages with the same numbers."},"top_countries":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Top Countries","description":"Up to 10 countries (ISO codes, as Google gives them)."},"ga4_top_pages":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Ga4 Top Pages","description":"Up to 20 GA4 pages with sessions and engagement."},"ai_traffic":{"anyOf":[{"$ref":"#/components/schemas/AnalyticsSummaryAiTraffic"},{"type":"null"}],"description":"Visits from the answer engines; `null` when GA4 holds none."}},"additionalProperties":false,"type":"object","required":["has_data","date_start","date_end","top_queries","top_pages","top_countries","ga4_top_pages"],"title":"AnalyticsSummary","description":"The brand's top queries, pages and countries and its AI traffic, from the stored Google reads.","example":{"date_end":"2026-10-03","date_start":"2026-09-05","ga4_property_name":"rankprompt.com","ga4_top_pages":[],"gsc_site_url":"sc-domain:rankprompt.com","has_data":true,"last_sync_at":"2026-10-02T06:00:00+00:00","object":"analytics_summary","top_countries":[],"top_pages":[],"top_queries":[{"clicks":120,"impressions":3400,"query":"ai visibility tool"}]}},"AnalyticsSummaryAiTraffic":{"properties":{"total_sessions":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Sessions"},"total_key_events":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Key Events","description":"GA4 key events of those sessions."},"total_revenue":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Total Revenue","description":"GA4 revenue of those sessions."},"currency_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency Code","description":"The GA4 property's currency."},"sources":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Sources","description":"The split per engine."}},"additionalProperties":false,"type":"object","title":"AnalyticsSummaryAiTraffic","description":"Visits the answer engines sent and what they did."},"AnalyticsWindow":{"properties":{"start_date":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"title":"Start Date"},"end_date":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"title":"End Date"}},"additionalProperties":false,"type":"object","title":"AnalyticsWindow","description":"The window to pull again; omit it for the last 28 days."},"ArticleAiSource":{"properties":{"object":{"type":"string","const":"article_ai_source","title":"Object","default":"article_ai_source"},"engine":{"type":"string","title":"Engine","description":"The assistant, as named by Rank Prompt (e.g. `ChatGPT`, `Perplexity`)."},"sessions":{"type":"integer","minimum":0.0,"title":"Sessions","default":0},"users":{"type":"integer","minimum":0.0,"title":"Users","default":0},"key_events":{"type":"integer","minimum":0.0,"title":"Key Events","description":"GA4 key events in those sessions.","default":0}},"additionalProperties":false,"type":"object","required":["engine"],"title":"ArticleAiSource","description":"Visits one assistant referred to the article."},"ArticleAiTraffic":{"properties":{"object":{"type":"string","const":"article_ai_traffic","title":"Object","default":"article_ai_traffic"},"brief_id":{"type":"string","title":"Brief Id"},"published":{"type":"boolean","title":"Published","description":"False until the article is live somewhere.","default":false},"page_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Page Path","description":"The landing page GA4 counts the visits on."},"sessions":{"type":"integer","minimum":0.0,"title":"Sessions","description":"Sessions an AI assistant referred to the page.","default":0},"key_events":{"type":"integer","minimum":0.0,"title":"Key Events","default":0},"sources":{"items":{"$ref":"#/components/schemas/ArticleAiSource"},"type":"array","title":"Sources","description":"Per assistant, most visits first."}},"additionalProperties":false,"type":"object","required":["brief_id"],"title":"ArticleAiTraffic","description":"GA4 sessions that AI assistants referred to one published article, in the window."},"ArticleAiTrafficList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/ArticleAiTraffic"},"type":"array","title":"Data"},"connected":{"type":"boolean","title":"Connected","description":"A GA4 property is linked. False means no number can be read: Search Console never stands in."},"reconnect":{"type":"boolean","title":"Reconnect","description":"The Google grant expired: reconnect Google to read GA4.","default":false},"start_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Start Date","description":"First day of the window, YYYY-MM-DD."},"end_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"End Date","description":"Last day of the window, YYYY-MM-DD."}},"additionalProperties":false,"type":"object","required":["data","connected"],"title":"ArticleAiTrafficList","description":"AI visits for the briefs asked about. Ids the brand does not own are left out."},"AuthorPage":{"properties":{"object":{"type":"string","const":"author_page","title":"Object","description":"Always `author_page`.","default":"author_page"},"url":{"type":"string","title":"Url"},"domain":{"type":"string","title":"Domain"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"citations":{"type":"integer","minimum":0.0,"title":"Citations"},"prompt_count":{"type":"integer","minimum":0.0,"title":"Prompt Count"},"platforms":{"items":{"type":"string"},"type":"array","title":"Platforms","description":"Engines that cited it (an open set)."},"last_seen":{"type":"string","format":"date-time","title":"Last Seen"}},"additionalProperties":false,"type":"object","required":["url","domain","citations","prompt_count","platforms","last_seen"],"title":"AuthorPage","description":"One page an author wrote, with what the answers did with it under the filters."},"AuthorPageList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/AuthorPage"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"True when more items exist past this page. Fetch them with a larger `offset`."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of items matching the query, across all pages."},"limit":{"type":"integer","minimum":1.0,"title":"Limit","description":"Page size that was applied."},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of items skipped before this page."}},"additionalProperties":false,"type":"object","required":["data","has_more","total","limit","offset"],"title":"AuthorPageList","description":"A page of one author's cited pages, most cited first."},"AutopilotSlotSkip":{"properties":{"object":{"type":"string","const":"autopilot_slot_skip","title":"Object","default":"autopilot_slot_skip"},"slot_at":{"type":"string","title":"Slot At","description":"The slot, as `GET /v1/brands/{brand_id}/content-calendar` lists it."},"skipped":{"type":"boolean","title":"Skipped","description":"True when the slot is now skipped, false when it was given back."},"next_run_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Next Run At","description":"The autopilot's next slot after the change."}},"additionalProperties":false,"type":"object","required":["slot_at","skipped"],"title":"AutopilotSlotSkip","description":"A coming slot left without an article, or given back, and the autopilot's next slot after it."},"AutopilotSlotSkipCreate":{"properties":{"slot_at":{"type":"string","format":"date-time","title":"Slot At","description":"One of the autopilot's coming slots, with its time zone."}},"additionalProperties":false,"type":"object","required":["slot_at"],"title":"AutopilotSlotSkipCreate"},"AvailableCompetitor":{"properties":{"domain":{"type":"string","title":"Domain"},"name":{"type":"string","title":"Name"},"cached":{"type":"boolean","title":"Cached"},"stale":{"type":"boolean","title":"Stale"},"fetched_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Fetched At"}},"type":"object","required":["domain","name","cached","stale"],"title":"AvailableCompetitor"},"BacklinkCheck":{"properties":{"id":{"type":"string","title":"Id"},"checked_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Checked At"},"status":{"type":"string","enum":["live","lost","rel_changed","url_changed","unreachable"],"title":"Status"},"href":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Href","description":"The link to the brand found, when there was one."},"anchor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Anchor"},"is_nofollow":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Nofollow"},"is_sponsored":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Sponsored"},"is_ugc":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Ugc"}},"type":"object","required":["id","status"],"title":"BacklinkCheck","description":"One weekly re-read of a won backlink."},"BacklinkCheckList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/BacklinkCheck"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"True when more items exist past this page. Fetch them with a larger `offset`."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of items matching the query, across all pages."},"limit":{"type":"integer","minimum":1.0,"title":"Limit","description":"Page size that was applied."},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of items skipped before this page."}},"additionalProperties":false,"type":"object","required":["data","has_more","total","limit","offset"],"title":"BacklinkCheckList","description":"A citation's weekly re-reads, newest first."},"BacklinkVerification":{"properties":{"object":{"type":"string","const":"backlink_verification","title":"Object","default":"backlink_verification"},"citation_id":{"type":"string","title":"Citation Id","description":"The cited page's id."},"has_backlink":{"type":"boolean","title":"Has Backlink","description":"Whether the page links to the brand's site."},"backlink_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Backlink Url","description":"The brand URL the page links to."},"anchor_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Anchor Text","description":"The link's anchor text."},"backlink_count":{"type":"integer","minimum":0.0,"title":"Backlink Count","description":"How many links to the brand the page holds."},"is_nofollow":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Nofollow","description":"`rel=nofollow`; `null` when the link was found in the text and its markup is unknown."},"is_sponsored":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Sponsored","description":"`rel=sponsored`; `null` as for `is_nofollow`."},"is_ugc":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Ugc","description":"`rel=ugc`; `null` as for `is_nofollow`."},"verified_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Verified At","description":"When the page was read."},"method":{"anyOf":[{"type":"string","enum":["parser","redirect","llm_candidate"]},{"type":"null"}],"title":"Method","description":"`parser` (an anchor in the markup), `redirect` (a link that lands on the brand once followed), or `llm_candidate` (a model's pick that did not confirm: `has_backlink` is `false`)."},"candidate_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Candidate Url","description":"The unconfirmed link when `method` is `llm_candidate`."}},"additionalProperties":false,"type":"object","required":["citation_id","has_backlink","backlink_count"],"title":"BacklinkVerification","description":"Whether a cited page links to the brand, read now.","example":{"anchor_text":"adidas Adizero Boston 12","backlink_count":1,"backlink_url":"https://www.adidas.com/us/adizero-boston-12-running-shoes","citation_id":"3c1f5a7e-8b2d-4e6f-9a0b-1c2d3e4f5a6b","has_backlink":true,"is_nofollow":false,"is_sponsored":false,"is_ugc":false,"method":"parser","object":"backlink_verification","verified_at":"2026-10-03T09:00:00+00:00"}},"Brand":{"properties":{"object":{"type":"string","title":"Object","description":"Always `brand`.","default":"brand"},"id":{"type":"string","title":"Id","description":"Stable brand identifier (UUID)."},"name":{"type":"string","title":"Name","description":"Display name of the brand."},"website":{"type":"string","title":"Website","description":"Primary brand website URL. Always present; `website` is required at create time."},"owned_domains":{"items":{"type":"string"},"type":"array","title":"Owned Domains","description":"The sites the brand owns: its website's domain and the ones its home page declares as itself (canonical, hreflang), once the site is read. A citation on any of them is the brand's own. On a host many sites share it is the brand's path (`linktr.ee/adidas`); empty when the website owns nothing."},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language","description":"Primary language (English name like `English`, `Spanish`)."},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country","description":"Primary country (e.g. `United States`, `Argentina`)."},"brand_aliases":{"items":{"type":"string"},"type":"array","title":"Brand Aliases","description":"Alternate names used for citation matching."},"categories":{"items":{"type":"string"},"type":"array","title":"Categories","description":"Free-form industry/topic category tags assigned to the brand (e.g. `running shoes`, `saas`, `fintech`). Used to seed prompt generation."},"brand_info_summary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brand Info Summary","description":"Short description derived from the latest brand audit. Null when no audit has run."},"is_local_business":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Local Business","description":"Whether customers come to the brand's place or it serves a bounded area (a dentist, a plumber). Set by brand research or by you; null until analysed. A city on each market is recommended when true."},"tags":{"items":{"type":"string"},"type":"array","title":"Tags","description":"Tags that organise your brands, on any plan."},"client_email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Client Email","description":"Agency client-contact email for the brand."},"client_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Client Name","description":"Agency client-contact name for the brand."},"client_company":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Client Company","description":"Agency client-contact company for the brand."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"ISO-8601 timestamp when the brand was created."},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"ISO-8601 timestamp of the last update."}},"additionalProperties":false,"type":"object","required":["id","name","website","created_at","updated_at"],"title":"Brand","description":"A brand.","example":{"brand_aliases":["adidas Originals","adidas AG","adidas Running"],"brand_info_summary":"Sportswear company founded in 1949 in Herzogenaurach, Germany, known for running shoes like Ultraboost and Adizero.","categories":["running shoes","sportswear","footwear"],"client_company":"adidas America Inc.","client_email":"jordan@e2e.test","client_name":"Jordan Rivera","country":"United States","created_at":"2024-08-12T15:23:04.512+00:00","id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","is_local_business":false,"language":"English","name":"adidas","object":"brand","owned_domains":["adidas.com","adidas.de"],"tags":["priority","west-coast"],"updated_at":"2024-09-01T11:08:42.117+00:00","website":"https://www.adidas.com"}},"BrandAudit":{"properties":{"object":{"type":"string","const":"brand_audit","title":"Object","description":"Always `brand_audit`.","default":"brand_audit"},"id":{"type":"string","title":"Id","description":"Brand audit id (UUID)."},"brand_id":{"type":"string","title":"Brand Id","description":"Owning brand id (UUID)."},"status":{"type":"string","enum":["processing","completed","failed"],"title":"Status","description":"Audit lifecycle state. One of `processing`, `completed`, `failed`."},"country":{"type":"string","title":"Country","description":"Country the audit was run for."},"location":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location","description":"Optional finer-grained location."},"language":{"type":"string","title":"Language","description":"Language the audit prompt was run in."},"prompt":{"type":"string","title":"Prompt","description":"Generated brand-visibility prompt sent to the AI platforms."},"key_themes":{"anyOf":[{"additionalProperties":true,"type":"object"},{"items":{},"type":"array"},{"type":"null"}],"title":"Key Themes","description":"Recurring themes detected across AI responses."},"citation_analysis":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Citation Analysis","description":"Per-page citation analysis rollup, when any pages have been analyzed."},"recommendations":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Recommendations","description":"Generated recommendations payload, when recommendations have been produced."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the audit was created."},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Updated At","description":"When the audit row was last updated."},"web_search_results":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Web Search Results","description":"Per-platform web-search results (keyed by provider)."},"knowledge_results":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Knowledge Results","description":"Per-platform knowledge (no-web-search) results (keyed by provider)."},"reputation_prompt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reputation Prompt","description":"Generated brand-reputation prompt, when a reputation pass was run."},"reputation_web_search_results":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Reputation Web Search Results","description":"Per-platform reputation web-search results (keyed by provider)."},"reputation_knowledge_results":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Reputation Knowledge Results","description":"Per-platform reputation knowledge results (keyed by provider)."},"dismissed_sources":{"items":{"type":"string"},"type":"array","title":"Dismissed Sources","description":"Cited URLs of this audit that the brand dismissed: the app leaves them out of the citations table and every count. Each web-search result also carries `source_verdicts`, whether each source is about the brand."},"own_domains":{"items":{"type":"string"},"type":"array","title":"Own Domains","description":"What the audit counts as the brand's own site: its website's domain and the sites its home page declares as itself (the canonical address and hreflang alternates at a site root, `munidepot.com` for `munidepot.com.ar`), each owning its subdomains, or a site on a shared host (`rank-prompt-e2e.webflow.io`). A citation on any of them is `owned`; a same-name site the home page does not declare is not."},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message","description":"User-facing failure reason when `status` is `failed`."}},"additionalProperties":false,"type":"object","required":["id","brand_id","status","country","language","prompt","created_at"],"title":"BrandAudit","description":"A complete brand audit, including the full per-platform analysis and reputation results."},"BrandAuditCitationAnalysisDispatched":{"properties":{"object":{"type":"string","const":"job_ref","title":"Object","description":"Always `job_ref`.","default":"job_ref"},"job_id":{"type":"string","title":"Job Id","description":"Poll this job on `GET /v1/jobs/{job_id}` until it completes."},"audit_id":{"type":"string","title":"Audit Id","description":"The audit the analysis is enriching."}},"additionalProperties":false,"type":"object","required":["job_id","audit_id"],"title":"BrandAuditCitationAnalysisDispatched","description":"Acknowledgement that a citation analysis job was queued."},"BrandAuditCitationAnalysisRequest":{"properties":{"urls":{"items":{"type":"string"},"type":"array","maxItems":30,"minItems":1,"title":"Urls","description":"Public page URLs to analyze (1-30). Each must be a reachable public HTTPS page."}},"additionalProperties":false,"type":"object","required":["urls"],"title":"BrandAuditCitationAnalysisRequest","description":"Kick off a deep citation analysis of specific pages for a completed audit."},"BrandAuditCreate":{"properties":{"country":{"type":"string","maxLength":100,"minLength":1,"title":"Country","description":"Country to audit visibility for (e.g. `United States`)."},"language":{"type":"string","maxLength":50,"minLength":1,"title":"Language","description":"Language to run the audit in (e.g. `English`)."},"location":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Location","description":"Optional finer-grained location within the country."}},"additionalProperties":false,"type":"object","required":["country","language"],"title":"BrandAuditCreate","description":"Run a new brand audit for a market (costs credits, runs the AI analysis inline)."},"BrandAuditDispatched":{"properties":{"object":{"type":"string","const":"brand_audit.run.dispatched","title":"Object","description":"Always `brand_audit.run.dispatched`.","default":"brand_audit.run.dispatched"},"brand_id":{"type":"string","title":"Brand Id","description":"Brand the audit is running for."},"audit_id":{"type":"string","title":"Audit Id","description":"The audit that was created. It stays in `processing` until the run finishes."},"job_id":{"type":"string","title":"Job Id","description":"Poll `GET /v1/jobs/{job_id}` for progress. Equal to `audit_id`, since one audit is one job."}},"additionalProperties":false,"type":"object","required":["brand_id","audit_id","job_id"],"title":"BrandAuditDispatched","description":"Response body for ``POST /v1/brands/{brand_id}/audits/runs``.","example":{"audit_id":"8c2d4f1e-5a3b-4c7d-9e1f-2a3b4c5d6e7f","brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","job_id":"8c2d4f1e-5a3b-4c7d-9e1f-2a3b4c5d6e7f","object":"brand_audit.run.dispatched"}},"BrandAuditList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/BrandAuditSummary"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Opaque continuation token. Pass back as `?cursor=` to fetch the next page. `null` when `has_more` is false."}},"additionalProperties":false,"type":"object","required":["data","has_more"],"title":"BrandAuditList","description":"A cursor-paginated page of brand audits."},"BrandAuditRecommendations":{"properties":{"force_regenerate":{"type":"boolean","title":"Force Regenerate","description":"Regenerate even if recommendations already exist (charges credits again).","default":false},"async":{"type":"boolean","title":"Async","description":"Queue the generation and answer `202` with a `job_id` at once, instead of waiting for it. Poll `GET /v1/jobs/{job_id}`, then read the audit.","default":false}},"additionalProperties":false,"type":"object","title":"BrandAuditRecommendations","description":"Generate SEO/AEO recommendations for a completed audit."},"BrandAuditRecommendationsDispatched":{"properties":{"object":{"type":"string","const":"job_ref","title":"Object","description":"Always `job_ref`.","default":"job_ref"},"job_id":{"type":"string","title":"Job Id","description":"Poll this job on `GET /v1/jobs/{job_id}` until it completes."},"audit_id":{"type":"string","title":"Audit Id","description":"The audit the recommendations are for."}},"additionalProperties":false,"type":"object","required":["job_id","audit_id"],"title":"BrandAuditRecommendationsDispatched","description":"Acknowledgement that the recommendations were queued; their credits are already held."},"BrandAuditShare":{"properties":{"object":{"type":"string","const":"brand_audit.share","title":"Object","description":"Always `brand_audit.share`.","default":"brand_audit.share"},"id":{"type":"string","title":"Id","description":"Share id (UUID)."},"audit_id":{"type":"string","title":"Audit Id","description":"Owning brand-audit id (UUID)."},"brand_id":{"type":"string","title":"Brand Id","description":"Owning brand id (UUID)."},"share_type":{"type":"string","const":"brand_audit","title":"Share Type","description":"Always `brand_audit`.","default":"brand_audit"},"access_token":{"type":"string","title":"Access Token","description":"URL-safe public token. Treat as secret; rotate via `POST` with `rotate=true`."},"share_url":{"type":"string","title":"Share Url","description":"Pre-rendered public URL to send to recipients."},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Expires At","description":"ISO-8601 timestamp after which the share returns `410 Gone`."},"is_existing":{"type":"boolean","title":"Is Existing","description":"`true` when the response refreshed an existing share rather than creating a new row.","default":false},"white_label_config":{"anyOf":[{"$ref":"#/components/schemas/ShareWhiteLabel"},{"type":"null"}],"description":"Account-level white-label branding applied to this share; null when the caller has none."},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Created At","description":"ISO-8601 timestamp the share row was first written."},"view_count":{"type":"integer","minimum":0.0,"title":"View Count","description":"Times this share has been viewed.","default":0},"last_viewed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Last Viewed At","description":"ISO-8601 timestamp the share was last viewed."},"has_password":{"type":"boolean","title":"Has Password","description":"Whether the share requires a password.","default":false}},"additionalProperties":false,"type":"object","required":["id","audit_id","brand_id","access_token","share_url"],"title":"BrandAuditShare","description":"A share link to a public, time-limited snapshot of a single brand audit.","example":{"access_token":"Hk2L8x9PqRsTuVwXyZ-aBcDeFgHiJkLmNoPqRsTuVwXyZ_AbCdE","audit_id":"8a72d9f1-c4b5-4e6d-9b1f-0e3a2c6d8b04","brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","created_at":"2026-04-20T15:23:04.512+00:00","expires_at":"2026-05-20T15:23:04.512+00:00","id":"0d2c1b3a-4e5f-6789-abcd-ef0123456789","is_existing":false,"object":"brand_audit.share","share_type":"brand_audit","share_url":"https://app.rankprompt.com/shared/Hk2L8x9PqRsTuVwXyZ-aBcDeFgHiJkLmNoPqRsTuVwXyZ_AbCdE"}},"BrandAuditShareCreate":{"properties":{"expiration_days":{"type":"integer","maximum":365.0,"minimum":1.0,"title":"Expiration Days","description":"Days until the share expires (1-365, default 30).","default":30},"rotate":{"type":"boolean","title":"Rotate","description":"When `true`, revoke every existing share the caller owns for this brand audit and issue a fresh token. Default `false` keeps `POST` idempotent: it returns the existing link to the audit's published document.","default":false},"password":{"anyOf":[{"type":"string","maxLength":128,"minLength":4},{"type":"null"}],"title":"Password","description":"Optional password to protect the share."}},"additionalProperties":false,"type":"object","title":"BrandAuditShareCreate","description":"Body for ``POST /v1/brands/{brand_id}/audits/{audit_id}/shares``.","example":{"expiration_days":30,"rotate":false}},"BrandAuditShareList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/BrandAuditShare"},"type":"array","title":"Data"}},"additionalProperties":false,"type":"object","required":["data"],"title":"BrandAuditShareList","description":"The caller's non-expired shares for one brand audit, newest first.","example":{"data":[{"access_token":"Hk2L8x9PqRsTuVwXyZ-aBcDeFgHiJkLmNoPqRsTuVwXyZ_AbCdE","audit_id":"8a72d9f1-c4b5-4e6d-9b1f-0e3a2c6d8b04","brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","created_at":"2026-04-20T15:23:04.512+00:00","expires_at":"2026-05-20T15:23:04.512+00:00","id":"0d2c1b3a-4e5f-6789-abcd-ef0123456789","is_existing":false,"object":"brand_audit.share","share_type":"brand_audit","share_url":"https://app.rankprompt.com/shared/Hk2L8x9PqRsTuVwXyZ-aBcDeFgHiJkLmNoPqRsTuVwXyZ_AbCdE"}],"object":"list"}},"BrandAuditShareUpdate":{"properties":{"expiration_days":{"type":"integer","maximum":365.0,"minimum":1.0,"title":"Expiration Days","description":"New expiry window from now (1-365 days). Replaces the current `expires_at`."}},"additionalProperties":false,"type":"object","required":["expiration_days"],"title":"BrandAuditShareUpdate","description":"Body for ``PATCH /v1/brands/{brand_id}/audits/{audit_id}/shares/{share_id}``.","example":{"expiration_days":60}},"BrandAuditSummary":{"properties":{"object":{"type":"string","const":"brand_audit","title":"Object","description":"Always `brand_audit`.","default":"brand_audit"},"id":{"type":"string","title":"Id","description":"Brand audit id (UUID)."},"brand_id":{"type":"string","title":"Brand Id","description":"Owning brand id (UUID)."},"status":{"type":"string","enum":["processing","completed","failed"],"title":"Status","description":"Audit lifecycle state. One of `processing`, `completed`, `failed`."},"country":{"type":"string","title":"Country","description":"Country the audit was run for."},"location":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location","description":"Optional finer-grained location."},"language":{"type":"string","title":"Language","description":"Language the audit prompt was run in."},"prompt":{"type":"string","title":"Prompt","description":"Generated brand-visibility prompt sent to the AI platforms."},"key_themes":{"anyOf":[{"additionalProperties":true,"type":"object"},{"items":{},"type":"array"},{"type":"null"}],"title":"Key Themes","description":"Recurring themes detected across AI responses."},"citation_analysis":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Citation Analysis","description":"Per-page citation analysis rollup, when any pages have been analyzed."},"recommendations":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Recommendations","description":"Generated recommendations payload, when recommendations have been produced."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the audit was created."},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Updated At","description":"When the audit row was last updated."}},"additionalProperties":false,"type":"object","required":["id","brand_id","status","country","language","prompt","created_at"],"title":"BrandAuditSummary","description":"A brand audit as it appears in a list, with the large per-platform analysis payloads omitted."},"BrandFacts":{"properties":{"object":{"type":"string","title":"Object","description":"Always `brand_facts`.","default":"brand_facts"},"brand_id":{"type":"string","title":"Brand Id","description":"Owning brand id (UUID)."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Long-form brand description. Null when no research has produced one."},"industry":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Industry","description":"Free-form industry label (e.g. `Sportswear`)."},"tagline":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tagline","description":"Short marketing tagline if known."},"value_proposition":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Value Proposition","description":"Concise statement of the brand's primary value proposition."},"mission_statement":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mission Statement","description":"Brand mission statement when published."},"headquarters":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Headquarters","description":"City / region of the brand's headquarters."},"founded_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Founded Year","description":"Year the brand was founded."},"company_size":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Size","description":"Free-form size bucket (e.g. `11-50`)."},"key_facts":{"items":{"type":"string"},"type":"array","title":"Key Facts","description":"Short bullet-style facts surfaced by the latest research run."},"products":{"items":{"$ref":"#/components/schemas/BrandFactsProduct"},"type":"array","title":"Products","description":"Products offered by the brand."},"services":{"items":{"$ref":"#/components/schemas/BrandFactsProduct"},"type":"array","title":"Services","description":"Services offered by the brand."},"key_people":{"items":{"$ref":"#/components/schemas/BrandFactsPerson"},"type":"array","title":"Key People","description":"Notable people at the brand (founders, executives, etc.)."},"research_status":{"anyOf":[{"type":"string","enum":["complete","partial","not_found"]},{"type":"null"}],"title":"Research Status","description":"Outcome of the last regeneration (`complete`, `partial`, `not_found`). Null when never run."},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Updated At","description":"ISO-8601 timestamp of the last facts update."}},"additionalProperties":false,"type":"object","required":["brand_id"],"title":"BrandFacts","description":"Brand facts for one brand.","example":{"brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","company_size":"10,001+","description":"Sportswear company founded in 1949 by Adi Dassler, designing running, football and training shoes and apparel.","founded_year":1949,"headquarters":"Herzogenaurach, Germany","industry":"Sportswear","key_facts":["Founded in 1949 by Adi Dassler","Makes the Adizero racing line and Boost cushioning"],"key_people":[{"name":"Adi Dassler","role":"Founder"}],"object":"brand_facts","products":[{"description":"Running shoe with Boost cushioning.","featured":true,"name":"Ultraboost"}],"research_status":"complete","services":[{"description":"Run tracking and training plans.","featured":false,"name":"adidas Running app"}],"tagline":"Impossible Is Nothing","updated_at":"2024-09-01T11:08:42.117+00:00","value_proposition":"Running shoes for every pace, from Ultraboost daily trainers to the Adizero race line."}},"BrandFactsPerson":{"properties":{"name":{"type":"string","maxLength":250,"minLength":1,"title":"Name"},"role":{"type":"string","maxLength":250,"minLength":1,"title":"Role"}},"additionalProperties":false,"type":"object","required":["name","role"],"title":"BrandFactsPerson","description":"A key person at the brand (founder, executive, etc.)."},"BrandFactsProduct":{"properties":{"name":{"type":"string","maxLength":100,"minLength":1,"title":"Name"},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Description"},"url":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Url","description":"The offering's page on the brand's site. Articles link the one or two offerings closest to their keyword, once and never in the opening paragraph."},"featured":{"type":"boolean","title":"Featured","description":"A featured offering wins a tie on closeness, and is the one linked when no offering is close to the article's keyword (otherwise the first in the list). A new research run keeps it featured by name.","default":false}},"additionalProperties":false,"type":"object","required":["name"],"title":"BrandFactsProduct","description":"A product or service offered by the brand."},"BrandFactsRegenerateDispatched":{"properties":{"object":{"type":"string","title":"Object","description":"Always `brand_facts.regenerate.dispatched`.","default":"brand_facts.regenerate.dispatched"},"brand_id":{"type":"string","title":"Brand Id","description":"Owning brand id (UUID)."},"job_id":{"type":"string","title":"Job Id","description":"Identifier of the background research job. Poll `GET /v1/jobs/{job_id}` until `status` is `completed` (or `failed` / `cancelled`)."}},"additionalProperties":false,"type":"object","required":["brand_id","job_id"],"title":"BrandFactsRegenerateDispatched","description":"Response body for ``POST /v1/brands/{brand_id}/facts``.","example":{"brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","job_id":"01J5KM4V8H6R7Q5XRZJZG6F8KQ","object":"brand_facts.regenerate.dispatched"}},"BrandFactsUpdate":{"properties":{"description":{"anyOf":[{"type":"string","maxLength":3500},{"type":"null"}],"title":"Description","description":"Long-form brand description. Pass `null` to clear, omit to leave unchanged."},"industry":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Industry"},"tagline":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Tagline"},"value_proposition":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Value Proposition"},"mission_statement":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Mission Statement"},"headquarters":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Headquarters"},"founded_year":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Founded Year","description":"Year founded, from 1 to the current year; a later year answers 422."},"company_size":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}],"title":"Company Size"},"key_facts":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":20},{"type":"null"}],"title":"Key Facts","description":"Replacement list of bullet-style facts (max 20 items, 500 chars each). Pass `null` to clear, omit to leave unchanged."},"products":{"anyOf":[{"items":{"$ref":"#/components/schemas/BrandFactsProduct"},"type":"array","maxItems":10},{"type":"null"}],"title":"Products","description":"Replacement list of products (max 10). Pass `null` to clear, omit to leave unchanged."},"services":{"anyOf":[{"items":{"$ref":"#/components/schemas/BrandFactsProduct"},"type":"array","maxItems":10},{"type":"null"}],"title":"Services","description":"Replacement list of services (max 10). Pass `null` to clear, omit to leave unchanged."},"key_people":{"anyOf":[{"items":{"$ref":"#/components/schemas/BrandFactsPerson"},"type":"array","maxItems":10},{"type":"null"}],"title":"Key People","description":"Replacement list of key people (max 10). Pass `null` to clear, omit to leave unchanged."}},"additionalProperties":false,"type":"object","title":"BrandFactsUpdate","description":"Partial-update body for ``PATCH /v1/brands/{brand_id}/facts``.","examples":[{"description":"Hand-written brand description.","industry":"Sportswear"},{"key_facts":["Founded 1949","Headquartered in Herzogenaurach"]},{},{"key_people":[{"name":"Adi Dassler","role":"Founder"}],"products":[{"description":"Marathon racing shoe.","name":"Adizero Adios Pro"}]}]},"BrandList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/Brand"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Opaque continuation token. Pass back as `?cursor=` to fetch the next page. `null` when `has_more` is false."}},"additionalProperties":false,"type":"object","required":["data","has_more"],"title":"BrandList","description":"Cursor-paginated list of brands.","example":{"data":[{"brand_aliases":["adidas Originals","adidas AG","adidas Running"],"brand_info_summary":"Sportswear company founded in 1949 in Herzogenaurach, Germany, known for running shoes like Ultraboost and Adizero.","categories":["running shoes","sportswear","footwear"],"client_company":"adidas America Inc.","client_email":"jordan@e2e.test","client_name":"Jordan Rivera","country":"United States","created_at":"2024-08-12T15:23:04.512+00:00","id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","is_local_business":false,"language":"English","name":"adidas","object":"brand","owned_domains":["adidas.com","adidas.de"],"tags":["priority","west-coast"],"updated_at":"2024-09-01T11:08:42.117+00:00","website":"https://www.adidas.com"}],"has_more":false,"object":"list"}},"BrandPrompt":{"properties":{"object":{"type":"string","const":"brand_prompt","title":"Object","description":"Always `brand_prompt`.","default":"brand_prompt"},"prompt_hash":{"type":"string","title":"Prompt Hash","description":"Stable id of the text: SHA-1 of it lower cased, whitespace collapsed."},"prompt_text":{"type":"string","title":"Prompt Text","description":"The prompt as sent to the engines."},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category","description":"Free-form category bucket."},"prompt_type":{"type":"string","enum":["brand","competitor","organic"],"title":"Prompt Type","description":"`brand` when the text names the brand, `competitor` when it names a direct or indirect competitor from the registry, `organic` otherwise."},"tracked":{"items":{"$ref":"#/components/schemas/BrandPromptPlacement"},"type":"array","title":"Tracked","description":"Scheduled Report locations tracking it; empty for a prompt that only ran in one-off reports."},"tracked_active":{"type":"boolean","title":"Tracked Active","description":"True when at least one placement is active."},"one_off_runs":{"type":"integer","minimum":0.0,"title":"One Off Runs","description":"Runs in reports outside any schedule."},"runs":{"type":"integer","minimum":0.0,"title":"Runs","description":"Completed runs of this text, scheduled and one-off."},"results":{"type":"integer","minimum":0.0,"title":"Results","description":"Engine answers across those runs."},"visibility":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Visibility","description":"Percent of those answers naming the brand (0-100), `null` before any answer."},"best_rank":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Best Rank","description":"Best position the brand reached in an answer."},"last_run_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"format":"date-time","title":"Last Run At","description":"When it last ran in a completed report."},"platforms":{"items":{"type":"string"},"type":"array","title":"Platforms","description":"Engines that answered it (an open set, e.g. `chatgpt`, `gemini`)."},"head_keyword":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Head Keyword","description":"The Google keyword the prompt stands for, once mapped."},"intent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Intent","description":"Search intent of that keyword, once mapped: `informational`, `commercial`, `transactional`, `navigational` or `local`."},"difficulty":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Difficulty","description":"AI difficulty from 0 to 100, once scored."},"trend":{"items":{"$ref":"#/components/schemas/BrandPromptTrendPoint"},"type":"array","title":"Trend","description":"Visibility on each of the last 12 days it was answered, oldest first."},"mentions":{"type":"integer","minimum":0.0,"title":"Mentions","description":"Answers naming the brand across those runs."},"languages":{"items":{"type":"string"},"type":"array","title":"Languages","description":"Languages it is tracked or ran in, e.g. `English`."},"volume":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Volume","description":"Monthly Google searches of its keyword in the brand's market, once the keyword metrics are cached."},"platform_results":{"items":{"$ref":"#/components/schemas/BrandPromptPlatformResult"},"type":"array","title":"Platform Results","description":"Answers, mentions and the brand's mean position per engine, over every answer."},"brands_named":{"items":{"$ref":"#/components/schemas/BrandPromptNamedBrand"},"type":"array","title":"Brands Named","description":"Brands every answer under the filters names: most answers first, then the better mean position, then the name."},"domains_cited":{"items":{"$ref":"#/components/schemas/BrandPromptCitedDomain"},"type":"array","title":"Domains Cited","description":"Domains every answer under the filters cites: most answers first, then the better mean position, then the domain."}},"additionalProperties":false,"type":"object","required":["prompt_hash","prompt_text","prompt_type","tracked","tracked_active","one_off_runs","runs","results","platforms","trend","mentions","languages","platform_results","brands_named","domains_cited"],"title":"BrandPrompt","description":"One prompt text of the brand, with every run of it counted together.","example":{"best_rank":2,"brands_named":[{"answers":21,"category":"my_brand","name":"adidas","position":2.0},{"answers":21,"category":"direct_competitor","name":"Nike","position":2.4}],"category":"Marathon","difficulty":62,"domains_cited":[{"answers":17,"domain":"runnersworld.com","position":1.5}],"head_keyword":"marathon running shoes","intent":"commercial","languages":["English"],"last_run_at":"2026-09-20T08:15:00+00:00","mentions":21,"object":"brand_prompt","one_off_runs":1,"platform_results":[{"mentions":4,"platform":"chatgpt","position":2.3,"results":9}],"platforms":["chatgpt","gemini","perplexity"],"prompt_hash":"6f1ed002ab5595859014ebf0951522d9c47f3ab1","prompt_text":"Which running shoes are best for a first marathon?","prompt_type":"organic","results":54,"runs":9,"tracked":[{"active":true,"country":"United States","id":"018e7c2c-33ab-7df1-b1cd-2ac3a8f9112d","intent":"consideration","language":"English","region_config_id":"2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6e","region_name":"United States","scheduled_report_id":"7b1d4c2e-5a6f-4e8b-9c0d-1e2f3a4b5c6d","scheduled_report_name":"Weekly US tracking"}],"tracked_active":true,"trend":[{"day":"2026-09-13","visibility":33.3},{"day":"2026-09-20","visibility":44.4}],"visibility":38.9,"volume":12100}},"BrandPromptCategoryCount":{"properties":{"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category","description":"The category, `null` for prompts without one."},"prompts":{"type":"integer","minimum":0.0,"title":"Prompts","description":"Prompts in the category."},"tracked":{"type":"integer","minimum":0.0,"title":"Tracked","description":"Of those, the prompts on a Scheduled Report."},"results":{"type":"integer","minimum":0.0,"title":"Results","description":"Engine answers to them."},"mentions":{"type":"integer","minimum":0.0,"title":"Mentions","description":"Of those answers, the ones naming the brand."}},"additionalProperties":false,"type":"object","required":["prompts","tracked","results","mentions"],"title":"BrandPromptCategoryCount","description":"Prompts, answers and mentions of one category."},"BrandPromptCitedDomain":{"properties":{"domain":{"type":"string","title":"Domain","description":"The cited host without `www.`."},"answers":{"type":"integer","minimum":1.0,"title":"Answers","description":"Answers citing a page of it."},"position":{"type":"number","title":"Position","description":"Its mean first place among each of those answers' citations, 1 is first."}},"additionalProperties":false,"type":"object","required":["domain","answers","position"],"title":"BrandPromptCitedDomain","description":"A domain the prompt's answers cite."},"BrandPromptFacets":{"properties":{"object":{"type":"string","const":"brand_prompt_facets","title":"Object","description":"Always `brand_prompt_facets`.","default":"brand_prompt_facets"},"type":{"$ref":"#/components/schemas/BrandPromptTypeCounts","description":"Prompts per `type`, under every filter but `type`."},"intent":{"additionalProperties":{"type":"integer"},"type":"object","title":"Intent","description":"Prompts per keyword intent, under every filter but `intent`: `informational`, `commercial`, `transactional`, `navigational`, `local`, and `unmapped` for prompts without a keyword yet. An intent with no prompt is left out."},"categories":{"items":{"$ref":"#/components/schemas/BrandPromptCategoryCount"},"type":"array","title":"Categories","description":"One row per category under every filter but `category`, the largest first."}},"additionalProperties":false,"type":"object","required":["type","intent","categories"],"title":"BrandPromptFacets","description":"Counts by type, intent and category, each ignoring its own filter and keeping the others.","example":{"categories":[{"category":"Marathon","mentions":118,"prompts":12,"results":324,"tracked":9}],"intent":{"commercial":21,"informational":18,"unmapped":13},"object":"brand_prompt_facets","type":{"brand":4,"competitor":11,"organic":37}}},"BrandPromptList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/BrandPrompt"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"True when more items exist past this page. Fetch them with a larger `offset`."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of items matching the query, across all pages."},"limit":{"type":"integer","minimum":1.0,"title":"Limit","description":"Page size that was applied."},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of items skipped before this page."},"facets":{"anyOf":[{"$ref":"#/components/schemas/BrandPromptFacets"},{"type":"null"}],"description":"Counts by type, intent and category across every page; `null` when none came back."}},"additionalProperties":false,"type":"object","required":["data","has_more","total","limit","offset"],"title":"BrandPromptList","description":"A page of the brand's prompts, with the counts by type, intent and category.","example":{"data":[{"best_rank":2,"brands_named":[{"answers":21,"category":"my_brand","name":"adidas","position":2.0},{"answers":21,"category":"direct_competitor","name":"Nike","position":2.4}],"category":"Marathon","difficulty":62,"domains_cited":[{"answers":17,"domain":"runnersworld.com","position":1.5}],"head_keyword":"marathon running shoes","intent":"commercial","languages":["English"],"last_run_at":"2026-09-20T08:15:00+00:00","mentions":21,"object":"brand_prompt","one_off_runs":1,"platform_results":[{"mentions":4,"platform":"chatgpt","position":2.3,"results":9}],"platforms":["chatgpt","gemini","perplexity"],"prompt_hash":"6f1ed002ab5595859014ebf0951522d9c47f3ab1","prompt_text":"Which running shoes are best for a first marathon?","prompt_type":"organic","results":54,"runs":9,"tracked":[{"active":true,"country":"United States","id":"018e7c2c-33ab-7df1-b1cd-2ac3a8f9112d","intent":"consideration","language":"English","region_config_id":"2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6e","region_name":"United States","scheduled_report_id":"7b1d4c2e-5a6f-4e8b-9c0d-1e2f3a4b5c6d","scheduled_report_name":"Weekly US tracking"}],"tracked_active":true,"trend":[{"day":"2026-09-13","visibility":33.3},{"day":"2026-09-20","visibility":44.4}],"visibility":38.9,"volume":12100}],"facets":{"categories":[{"category":"Marathon","mentions":118,"prompts":12,"results":324,"tracked":9}],"intent":{"commercial":21,"informational":18,"unmapped":13},"object":"brand_prompt_facets","type":{"brand":4,"competitor":11,"organic":37}},"has_more":false,"limit":100,"object":"list","offset":0,"total":1}},"BrandPromptNamedBrand":{"properties":{"name":{"type":"string","title":"Name","description":"The brand's own name, a registered competitor's canonical name (its aliases count with it), or the name as the answers wrote it."},"category":{"type":"string","title":"Category","description":"`my_brand`, `direct_competitor`, `indirect_competitor`, `ai_platform`, `publisher`, `other` or `uncategorized` (an open set): a registered competitor's relation in the brand's registry, else the answers' own."},"answers":{"type":"integer","minimum":1.0,"title":"Answers","description":"Answers naming it; the brand counts exactly where `brand_appears` is true."},"position":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Position","description":"Its mean first place among the brands each of those answers names, 1 is first; `null` when none of them lists it in order."},"website":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Website","description":"A registered competitor's website, from the brand's competitor registry; `null` for the brand itself and for a name the registry does not hold."}},"additionalProperties":false,"type":"object","required":["name","category","answers","position"],"title":"BrandPromptNamedBrand","description":"A brand the prompt's answers name."},"BrandPromptPlacement":{"properties":{"id":{"type":"string","title":"Id","description":"The tracked prompt's id in that location (a region-config prompt id)."},"scheduled_report_id":{"type":"string","title":"Scheduled Report Id","description":"Scheduled Report that tracks it."},"scheduled_report_name":{"type":"string","title":"Scheduled Report Name","description":"Name of that Scheduled Report."},"region_config_id":{"type":"string","title":"Region Config Id","description":"Location (region config) it runs in."},"region_name":{"type":"string","title":"Region Name","description":"Name of that location."},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country","description":"Full English country name, e.g. `United States`."},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language","description":"Language of the location, e.g. `English`."},"active":{"type":"boolean","title":"Active","description":"True when the prompt, the location and the schedule are all on."},"intent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Intent","description":"The prompt's funnel intent: `awareness` (learning about a topic), `consideration` (weighing options) or `decision` (choosing between named options); `null` when unclassified. Written with generated prompts, set by hand otherwise. An open set. Not the row's `intent`, which is the search intent of its keyword."}},"additionalProperties":false,"type":"object","required":["id","scheduled_report_id","scheduled_report_name","region_config_id","region_name","active"],"title":"BrandPromptPlacement","description":"Where a Scheduled Report tracks the prompt: one location of one schedule."},"BrandPromptPlatformResult":{"properties":{"platform":{"type":"string","title":"Platform","description":"The engine, e.g. `chatgpt`."},"results":{"type":"integer","minimum":0.0,"title":"Results","description":"Answers from this engine across the runs."},"mentions":{"type":"integer","minimum":0.0,"title":"Mentions","description":"Of those, the answers naming the brand."},"position":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Position","description":"The brand's mean position in the answers naming it, `null` when none does."}},"additionalProperties":false,"type":"object","required":["platform","results","mentions"],"title":"BrandPromptPlatformResult","description":"Every answer one engine gave the prompt under the filters."},"BrandPromptTrendPoint":{"properties":{"day":{"type":"string","format":"date","title":"Day","description":"The day the answers were given, in the `tz` asked (default UTC)."},"visibility":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Visibility","description":"Percent of that day's answers naming the brand."}},"additionalProperties":false,"type":"object","required":["day"],"title":"BrandPromptTrendPoint","description":"Visibility on one day the prompt was answered."},"BrandPromptTypeCounts":{"properties":{"brand":{"type":"integer","minimum":0.0,"title":"Brand","description":"Prompts that name the brand."},"competitor":{"type":"integer","minimum":0.0,"title":"Competitor","description":"Prompts that name a direct or indirect competitor."},"organic":{"type":"integer","minimum":0.0,"title":"Organic","description":"Prompts that name neither."}},"additionalProperties":false,"type":"object","required":["brand","competitor","organic"],"title":"BrandPromptTypeCounts","description":"Prompts per type."},"BrandPromptsUpdate":{"properties":{"ids":{"items":{"type":"string"},"type":"array","maxItems":500,"minItems":1,"title":"Ids","description":"Tracked prompt ids (UUIDs), the `tracked[].id` of the list rows; up to 500 per call. They may belong to different Scheduled Reports and locations of the brand."},"disabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Disabled","description":"`true` pauses them (they stop running and keep their history), `false` resumes them. A location tracks at most 50 active prompts; a resume past that is refused whole."},"category":{"anyOf":[{"type":"string","maxLength":100,"minLength":1},{"type":"null"}],"title":"Category","description":"Move them to this category."},"intent":{"anyOf":[{"type":"string","enum":["awareness","consideration","decision"]},{"type":"null"}],"title":"Intent","description":"New funnel intent: `awareness`, `consideration` or `decision`; `null` makes it unclassified."}},"additionalProperties":false,"type":"object","required":["ids"],"title":"BrandPromptsUpdate","description":"Body for ``PATCH /v1/brands/{brand_id}/prompts``.","example":{"disabled":true,"ids":["018e7c2c-33ab-7df1-b1cd-2ac3a8f9112d"]}},"BrandPromptsUpdated":{"properties":{"object":{"type":"string","const":"brand_prompts.update","title":"Object","description":"Always `brand_prompts.update`.","default":"brand_prompts.update"},"updated":{"type":"integer","minimum":0.0,"title":"Updated","description":"Tracked prompts changed."}},"additionalProperties":false,"type":"object","required":["updated"],"title":"BrandPromptsUpdated","description":"Response of ``PATCH /v1/brands/{brand_id}/prompts``.","example":{"object":"brand_prompts.update","updated":1}},"BrandShare":{"properties":{"object":{"type":"string","const":"brand.share","title":"Object","description":"Always `brand.share`.","default":"brand.share"},"id":{"type":"string","title":"Id","description":"Share id (UUID)."},"brand_id":{"type":"string","title":"Brand Id","description":"Owning brand id (UUID)."},"share_type":{"type":"string","const":"brand","title":"Share Type","description":"Always `brand`.","default":"brand"},"access_token":{"type":"string","title":"Access Token","description":"URL-safe public token. Treat as secret; rotate via `POST` with `rotate=true`."},"share_url":{"type":"string","title":"Share Url","description":"Pre-rendered public URL to send to recipients."},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Expires At","description":"ISO-8601 timestamp after which the share returns `410 Gone`."},"is_existing":{"type":"boolean","title":"Is Existing","description":"`true` when the response refreshed an existing share rather than creating a new row.","default":false},"white_label_config":{"anyOf":[{"$ref":"#/components/schemas/ShareWhiteLabel"},{"type":"null"}],"description":"Account-level white-label branding applied to this share; null when the caller has none."},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Created At","description":"ISO-8601 timestamp the share row was first written."},"view_count":{"type":"integer","minimum":0.0,"title":"View Count","description":"Times this share has been viewed.","default":0},"last_viewed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Last Viewed At","description":"ISO-8601 timestamp the share was last viewed."},"refresh_on_view":{"type":"boolean","title":"Refresh On View","description":"Whether the snapshot rebuilds on each view.","default":false},"has_password":{"type":"boolean","title":"Has Password","description":"Whether the share requires a password.","default":false}},"additionalProperties":false,"type":"object","required":["id","brand_id","access_token","share_url"],"title":"BrandShare","description":"A share link to a public, time-limited brand-summary snapshot.","example":{"access_token":"Hk2L8x9PqRsTuVwXyZ-aBcDeFgHiJkLmNoPqRsTuVwXyZ_AbCdE","brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","created_at":"2026-04-20T15:23:04.512+00:00","expires_at":"2026-05-20T15:23:04.512+00:00","id":"0d2c1b3a-4e5f-6789-abcd-ef0123456789","is_existing":false,"object":"brand.share","share_type":"brand","share_url":"https://app.rankprompt.com/shared/Hk2L8x9PqRsTuVwXyZ-aBcDeFgHiJkLmNoPqRsTuVwXyZ_AbCdE"}},"BrandShareCreate":{"properties":{"expiration_days":{"type":"integer","maximum":365.0,"minimum":1.0,"title":"Expiration Days","description":"Days until the share expires (1-365, default 30).","default":30},"rotate":{"type":"boolean","title":"Rotate","description":"When `true`, revoke every existing brand-summary share the caller owns on this brand and issue a fresh token. Default `false` keeps `POST` idempotent (refreshes the existing share's snapshot).","default":false},"report_ids":{"items":{"type":"string"},"type":"array","maxItems":100,"title":"Report Ids","description":"Reports to include in the snapshot. Up to 100; all must belong to this brand. The snapshot covers the runs of their markets on the days they ran (the date range widens to include them)."},"market_ids":{"items":{"type":"string"},"type":"array","maxItems":250,"title":"Market Ids","description":"Markets (a report's `market_id`, a region config's `id`) whose runs in the date range the snapshot shows; none and no `report_ids` shows every market."},"place":{"items":{"type":"string","maxLength":300,"minLength":1},"type":"array","maxItems":200,"title":"Place","description":"Places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake): their markets join `market_ids` in the snapshot."},"seo_page_ids":{"items":{"type":"string"},"type":"array","maxItems":100,"title":"Seo Page Ids","description":"SEO pages to include in the snapshot. Up to 100; all must belong to this brand."},"include_analytics":{"type":"boolean","title":"Include Analytics","description":"Include Google Analytics / Search Console summaries in the snapshot.","default":true},"include_content":{"type":"boolean","title":"Include Content","description":"Include published-content summaries in the snapshot.","default":true},"date_range_start":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Date Range Start","description":"ISO date (`YYYY-MM-DD`) lower bound for the runs, analytics and content. Defaults to 28 days before `date_range_end`."},"date_range_end":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Date Range End","description":"ISO date (`YYYY-MM-DD`) upper bound for the runs, analytics and content. Defaults to today."},"refresh_on_view":{"type":"boolean","title":"Refresh On View","description":"Whether the snapshot rebuilds on each view.","default":false},"password":{"anyOf":[{"type":"string","maxLength":128,"minLength":4},{"type":"null"}],"title":"Password","description":"Optional password to protect the share."}},"additionalProperties":false,"type":"object","title":"BrandShareCreate","description":"Body for ``POST /v1/brands/{brand_id}/shares``.","example":{"date_range_end":"2026-04-22","date_range_start":"2026-03-25","expiration_days":30,"include_analytics":true,"include_content":false,"report_ids":["8a72d9f1-c4b5-4e6d-9b1f-0e3a2c6d8b04"],"rotate":false,"seo_page_ids":[]}},"BrandShareList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/BrandShare"},"type":"array","title":"Data"}},"additionalProperties":false,"type":"object","required":["data"],"title":"BrandShareList","description":"The caller's non-expired brand-summary shares for one brand, newest first.","example":{"data":[{"access_token":"Hk2L8x9PqRsTuVwXyZ-aBcDeFgHiJkLmNoPqRsTuVwXyZ_AbCdE","brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","created_at":"2026-04-20T15:23:04.512+00:00","expires_at":"2026-05-20T15:23:04.512+00:00","id":"0d2c1b3a-4e5f-6789-abcd-ef0123456789","is_existing":false,"object":"brand.share","share_type":"brand","share_url":"https://app.rankprompt.com/shared/Hk2L8x9PqRsTuVwXyZ-aBcDeFgHiJkLmNoPqRsTuVwXyZ_AbCdE"}],"object":"list"}},"BrandShareUpdate":{"properties":{"expiration_days":{"type":"integer","maximum":365.0,"minimum":1.0,"title":"Expiration Days","description":"New expiry window from now (1-365 days). Replaces the current `expires_at`."}},"additionalProperties":false,"type":"object","required":["expiration_days"],"title":"BrandShareUpdate","description":"Body for ``PATCH /v1/brands/{brand_id}/shares/{share_id}``.","example":{"expiration_days":60}},"BusinessCategorized":{"properties":{"object":{"type":"string","title":"Object","description":"Always `business_categorized`.","default":"business_categorized"},"name":{"type":"string","title":"Name","description":"Canonical business name (variant spellings are resolved to one name)."},"category":{"anyOf":[{"type":"string","enum":["my_brand","direct_competitor","indirect_competitor","ai_platform","publisher","other","uncategorized"]},{"type":"null"}],"title":"Category","description":"One of `my_brand`, `direct_competitor`, `indirect_competitor`, `ai_platform`, `publisher`, `other`, `uncategorized`, or `null` when the classification step failed for this mention."},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"LLM-authored rationale for the classification. Null on classification failure."},"mentioned_as":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mentioned As","description":"Verbatim name variant used in the answer before canonical resolution."},"website":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Website","description":"The entity's official website URL when resolved, else null."}},"additionalProperties":false,"type":"object","required":["name"],"title":"BusinessCategorized","description":"One business name extracted from an AI answer, classified by the LLM.","example":{"category":"direct_competitor","mentioned_as":"Asics","name":"ASICS","object":"business_categorized","reason":"Running shoe brand frequently cited alongside the brand."}},"CacheState":{"properties":{"missing":{"type":"boolean","title":"Missing"},"stale":{"type":"boolean","title":"Stale"},"fetched_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Fetched At"}},"type":"object","required":["missing","stale"],"title":"CacheState"},"CalendarArticle":{"properties":{"object":{"type":"string","const":"calendar_article","title":"Object","description":"Always `calendar_article`.","default":"calendar_article"},"id":{"type":"string","title":"Id","description":"Content brief id."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"topic":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Topic"},"content_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content Type"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status","description":"The brief's status, e.g. `draft` or `needs_review`."},"planned_publish_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Planned Publish At","description":"Its plan date, if set."},"review_due_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Review Due At","description":"When its review is due, if set."},"market":{"anyOf":[{"$ref":"#/components/schemas/ContentBriefMarket"},{"type":"null"}],"description":"The market it was written for, when its source prompts share one."}},"additionalProperties":false,"type":"object","required":["id"],"title":"CalendarArticle","description":"An article the window holds."},"CalendarSlot":{"properties":{"object":{"type":"string","const":"calendar_slot","title":"Object","description":"Always `calendar_slot`.","default":"calendar_slot"},"id":{"type":"string","title":"Id","description":"Stable id of the slot within the calendar."},"source":{"type":"string","enum":["brief","generation","publish","queue","autopilot"],"title":"Source","description":"What dates it: `brief` (its plan date), `generation` (the run writing it, or the one that wrote an undated article), `publish` (a publish target), `queue` (a publish waiting in the queue) or `autopilot` (a slot the brand's autopilot will fill)."},"state":{"type":"string","enum":["planned","queued","generating","ready","scheduled","held","review","published","failed","missed"],"title":"State","description":"`planned`, `queued`, `generating`, `ready`, `scheduled`, `held` (its time came while the brand owner's plan did not include publishing: it goes out when the plan is back if its time is still ahead), `review` (a pull request waits to be merged), `published`, `failed` or `missed` (its time passed while it was `held`: move it to reschedule it)."},"at":{"type":"string","format":"date-time","title":"At","description":"The instant the slot sits on."},"brief_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brief Id","description":"The article; `null` for an autopilot slot."},"target_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Type","description":"Where it publishes, e.g. `cms_connection`."},"target_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Id","description":"The publish target id."},"target_provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Provider","description":"The platform of the target, e.g. `wordpress`."},"published_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Published Url","description":"The live URL once published."},"step":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Step","description":"The pipeline step while `generating`."},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Why it failed, when `failed`, or why it missed, when `missed`."},"review_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Review Url","description":"The pull request to merge, when `review`."},"schedule_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Schedule Id","description":"The queued publish of a `queue` slot (`scheduled`, `held` or `missed`); move it with `PATCH /v1/brands/{brand_id}/content-briefs/{brief_id}/publish-schedules/{schedule_id}`."},"task_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task Id","description":"The article's board task, when it has one."},"task_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task Status","description":"The board task's status, e.g. `backlog`, `review` or `approved`."},"review_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Review Status","description":"The client review's status: `pending`, `changes_requested` or `approved`."},"approved":{"type":"boolean","title":"Approved","description":"True when the board task is `approved` or the client approved the article.","default":false}},"additionalProperties":false,"type":"object","required":["id","source","state","at"],"title":"CalendarSlot","description":"One article on the calendar: where it stands and the instant it sits on."},"Campaign":{"properties":{"object":{"type":"string","const":"campaign","title":"Object","default":"campaign"},"id":{"type":"string","title":"Id","description":"Campaign id."},"brand_id":{"type":"string","title":"Brand Id","description":"Owning brand id."},"name":{"type":"string","title":"Name","description":"Name."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Description."},"status":{"type":"string","enum":["draft","active","paused","completed","archived"],"title":"Status","description":"`draft`, `active` (sending), `paused`, `completed` (ended for good) or `archived`."},"contact_list_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contact List Id","description":"The contact list it emails."},"template_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Template Id","description":"A single email it sends, as drafts to review."},"sequence_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sequence Id","description":"A sequence it runs, sending on its own."},"mailbox_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mailbox Id","description":"The mailbox it sends from."},"send_window_start":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Send Window Start","description":"Start of the daily window (`HH:MM`)."},"send_window_end":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Send Window End","description":"End of the daily window (`HH:MM`)."},"send_window_timezone":{"type":"string","title":"Send Window Timezone","description":"The window's IANA time zone."},"skip_weekends":{"type":"boolean","title":"Skip Weekends","description":"Whether it sends on weekends."},"daily_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Daily Limit","description":"The most it sends a day; the mailbox's cap also holds."},"send_interval_minutes":{"type":"integer","minimum":0.0,"title":"Send Interval Minutes","description":"Minutes between two sends; 0 sends as fast as allowed."},"re_enrollment_behavior":{"type":"string","enum":["skip","continue","restart"],"title":"Re Enrollment Behavior","description":"A contact already emailed by another campaign: `skip`, `continue` or `restart`."},"skip_unsubscribe_footer":{"type":"boolean","title":"Skip Unsubscribe Footer","description":"Whether its emails go out without an unsubscribe footer."},"stats":{"$ref":"#/components/schemas/CampaignStats","description":"What its emails did."},"next_scheduled_email":{"anyOf":[{"$ref":"#/components/schemas/CampaignNextEmail"},{"type":"null"}],"description":"The next email due, while it is active or paused."},"started_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Started At","description":"When it was launched."},"paused_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Paused At","description":"When it was last paused."},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Completed At","description":"When it was ended."},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Created At","description":"When it was created."},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Updated At","description":"Last change."}},"additionalProperties":false,"type":"object","required":["id","brand_id","name","status","send_window_timezone","skip_weekends","send_interval_minutes","re_enrollment_behavior","skip_unsubscribe_footer","stats"],"title":"Campaign","description":"A campaign: a contact list, a template or a sequence, the mailbox it sends from, and a send window.","example":{"brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","contact_list_id":"9b8a7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d","created_at":"2026-09-21T10:00:00+00:00","daily_limit":30,"id":"8192a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b","mailbox_id":"5e6f7081-92a3-4b4c-8d5e-6f708192a3b4","name":"Best running shoes lists","object":"campaign","re_enrollment_behavior":"skip","send_interval_minutes":10,"send_window_end":"17:00","send_window_start":"09:00","send_window_timezone":"America/New_York","sequence_id":"4d5e6f70-8192-4a3b-9c4d-5e6f7a8b9c0d","skip_unsubscribe_footer":true,"skip_weekends":true,"started_at":"2026-09-22T09:00:00+00:00","stats":{"bounce_rate":3.3,"emails_bounced":1,"emails_opened":18,"emails_replied":4,"emails_sent":30,"open_rate":60.0,"reply_rate":13.3,"total_emails":42},"status":"active","updated_at":"2026-09-22T09:00:00+00:00"}},"CampaignCreate":{"properties":{"description":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Description","description":"Description."},"contact_list_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contact List Id","description":"The contact list it emails."},"template_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Template Id","description":"A single email, sent as drafts to review."},"sequence_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sequence Id","description":"A sequence, which sends on its own."},"mailbox_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mailbox Id","description":"The mailbox, from `GET /v1/me/mailboxes`."},"send_window_start":{"anyOf":[{"type":"string","maxLength":8,"pattern":"^\\d{2}:\\d{2}(:\\d{2})?$"},{"type":"null"}],"title":"Send Window Start","description":"`HH:MM`."},"send_window_end":{"anyOf":[{"type":"string","maxLength":8,"pattern":"^\\d{2}:\\d{2}(:\\d{2})?$"},{"type":"null"}],"title":"Send Window End","description":"`HH:MM`."},"daily_limit":{"anyOf":[{"type":"integer","maximum":500.0,"minimum":1.0},{"type":"null"}],"title":"Daily Limit","description":"Emails a day (1 to 500)."},"re_enrollment_behavior":{"anyOf":[{"type":"string","enum":["skip","continue","restart"]},{"type":"null"}],"title":"Re Enrollment Behavior","description":"`skip` (default), `continue` or `restart`."},"skip_unsubscribe_footer":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Skip Unsubscribe Footer","description":"Send without an unsubscribe footer (default `true`)."},"name":{"type":"string","maxLength":200,"minLength":1,"title":"Name","description":"Name."},"send_window_timezone":{"type":"string","maxLength":50,"title":"Send Window Timezone","description":"An IANA time zone (default `UTC`).","default":"UTC"},"skip_weekends":{"type":"boolean","title":"Skip Weekends","description":"Skip weekends (default `true`).","default":true},"send_interval_minutes":{"type":"integer","minimum":0.0,"title":"Send Interval Minutes","description":"Minutes between two sends: 0, or 10 and up (default 0).","default":0}},"additionalProperties":false,"type":"object","required":["name"],"title":"CampaignCreate","description":"A new campaign; it starts as a draft and sends nothing until launched.","example":{"contact_list_id":"9b8a7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d","daily_limit":30,"mailbox_id":"5e6f7081-92a3-4b4c-8d5e-6f708192a3b4","name":"Best running shoes lists","send_window_end":"17:00","send_window_start":"09:00","send_window_timezone":"America/New_York","sequence_id":"4d5e6f70-8192-4a3b-9c4d-5e6f7a8b9c0d"}},"CampaignDay":{"properties":{"date":{"type":"string","title":"Date","description":"The day (`YYYY-MM-DD`)."},"sent":{"type":"integer","minimum":0.0,"title":"Sent","description":"Emails sent."},"opened":{"type":"integer","minimum":0.0,"title":"Opened","description":"Emails opened."},"replied":{"type":"integer","minimum":0.0,"title":"Replied","description":"Emails replied to."}},"additionalProperties":false,"type":"object","required":["date","sent","opened","replied"],"title":"CampaignDay","description":"One day of a campaign's sends."},"CampaignFirstEmail":{"properties":{"to":{"type":"string","title":"To","description":"The first contact's email."},"subject":{"type":"string","title":"Subject","description":"Subject, placeholders filled."},"body":{"type":"string","title":"Body","description":"HTML body, placeholders filled."},"body_text":{"type":"string","title":"Body Text","description":"Plain-text body."}},"additionalProperties":false,"type":"object","required":["to","subject","body","body_text"],"title":"CampaignFirstEmail","description":"The campaign's first email, filled in for the first contact."},"CampaignList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/Campaign"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Opaque continuation token. Pass back as `?cursor=` to fetch the next page. `null` when `has_more` is false."}},"additionalProperties":false,"type":"object","required":["data","has_more"],"title":"CampaignList","description":"A page of campaigns, newest first.","example":{"data":[{"brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","contact_list_id":"9b8a7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d","created_at":"2026-09-21T10:00:00+00:00","daily_limit":30,"id":"8192a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b","mailbox_id":"5e6f7081-92a3-4b4c-8d5e-6f708192a3b4","name":"Best running shoes lists","object":"campaign","re_enrollment_behavior":"skip","send_interval_minutes":10,"send_window_end":"17:00","send_window_start":"09:00","send_window_timezone":"America/New_York","sequence_id":"4d5e6f70-8192-4a3b-9c4d-5e6f7a8b9c0d","skip_unsubscribe_footer":true,"skip_weekends":true,"started_at":"2026-09-22T09:00:00+00:00","stats":{"bounce_rate":3.3,"emails_bounced":1,"emails_opened":18,"emails_replied":4,"emails_sent":30,"open_rate":60.0,"reply_rate":13.3,"total_emails":42},"status":"active","updated_at":"2026-09-22T09:00:00+00:00"}],"has_more":false,"object":"list"}},"CampaignNextEmail":{"properties":{"email_id":{"type":"string","title":"Email Id","description":"The email."},"recipient_email":{"type":"string","title":"Recipient Email","description":"Its recipient."},"recipient_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Recipient Name","description":"The recipient's name."},"subject":{"type":"string","title":"Subject","description":"Its subject."},"scheduled_for":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Scheduled For","description":"When it goes out."},"follow_up_number":{"type":"integer","minimum":0.0,"title":"Follow Up Number","description":"0 for the first email, then 1, 2... for follow-ups."}},"additionalProperties":false,"type":"object","required":["email_id","recipient_email","subject","follow_up_number"],"title":"CampaignNextEmail","description":"The next email due."},"CampaignPreview":{"properties":{"object":{"type":"string","const":"campaign_preview","title":"Object","default":"campaign_preview"},"campaign_id":{"type":"string","title":"Campaign Id","description":"The campaign."},"status":{"type":"string","enum":["draft","active","paused","completed","archived"],"title":"Status","description":"Its status now."},"mailbox":{"anyOf":[{"$ref":"#/components/schemas/Mailbox"},{"type":"null"}],"description":"The mailbox it sends from, with today's cap."},"recipients":{"type":"integer","minimum":0.0,"title":"Recipients","description":"Contacts on its list now."},"sample_recipients":{"items":{"$ref":"#/components/schemas/CampaignRecipient"},"type":"array","title":"Sample Recipients","description":"The first five."},"first_email":{"anyOf":[{"$ref":"#/components/schemas/CampaignFirstEmail"},{"type":"null"}],"description":"Its first email as the first contact with an email gets it."},"sends_as":{"type":"string","enum":["sequence","drafts"],"title":"Sends As","description":"`sequence`: emails go out on their own. `drafts`: a template's emails are saved as drafts to send."},"blockers":{"items":{"type":"string"},"type":"array","title":"Blockers","description":"What stops a launch now, in words."},"can_launch":{"type":"boolean","title":"Can Launch","description":"True when nothing blocks a launch."}},"additionalProperties":false,"type":"object","required":["campaign_id","status","recipients","sends_as","can_launch"],"title":"CampaignPreview","description":"What launching the campaign would do, and what blocks it.","example":{"blockers":["Campaign must have an email account"],"campaign_id":"8192a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b","can_launch":false,"first_email":{"body":"<p>Hi Alex</p>","body_text":"Hi Alex","subject":"Alex, a shoe for The best running shoes","to":"alex.rivera@e2e.test"},"object":"campaign_preview","recipients":42,"sample_recipients":[{"company":"Runner's World","contact_id":"7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d","email":"alex.rivera@e2e.test","name":"Alex Rivera"}],"sends_as":"sequence","status":"draft"}},"CampaignRecipient":{"properties":{"contact_id":{"type":"string","title":"Contact Id","description":"Contact id."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Name."},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email","description":"Email address."},"company":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company","description":"Company."}},"additionalProperties":false,"type":"object","required":["contact_id"],"title":"CampaignRecipient","description":"A contact the campaign would email."},"CampaignStats":{"properties":{"total_emails":{"type":"integer","minimum":0.0,"title":"Total Emails","description":"Emails the campaign created."},"emails_sent":{"type":"integer","minimum":0.0,"title":"Emails Sent","description":"Sent."},"emails_opened":{"type":"integer","minimum":0.0,"title":"Emails Opened","description":"Opened."},"emails_replied":{"type":"integer","minimum":0.0,"title":"Emails Replied","description":"Replied to."},"emails_bounced":{"type":"integer","minimum":0.0,"title":"Emails Bounced","description":"Bounced."},"open_rate":{"type":"number","title":"Open Rate","description":"Opened over sent, in percent."},"reply_rate":{"type":"number","title":"Reply Rate","description":"Replied over sent, in percent."},"bounce_rate":{"type":"number","title":"Bounce Rate","description":"Bounced over sent, in percent."}},"additionalProperties":false,"type":"object","required":["total_emails","emails_sent","emails_opened","emails_replied","emails_bounced","open_rate","reply_rate","bounce_rate"],"title":"CampaignStats","description":"What the campaign's emails did."},"CampaignTimeline":{"properties":{"object":{"type":"string","const":"campaign_timeline","title":"Object","default":"campaign_timeline"},"campaign_id":{"type":"string","title":"Campaign Id","description":"The campaign."},"days":{"items":{"$ref":"#/components/schemas/CampaignDay"},"type":"array","title":"Days","description":"One entry per day, oldest first."}},"additionalProperties":false,"type":"object","required":["campaign_id"],"title":"CampaignTimeline","description":"A campaign's sends, opens and replies per day.","example":{"campaign_id":"8192a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b","days":[{"date":"2026-09-22","opened":7,"replied":2,"sent":12}],"object":"campaign_timeline"}},"CampaignUpdate":{"properties":{"description":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Description","description":"Description."},"contact_list_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contact List Id","description":"The contact list it emails."},"template_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Template Id","description":"A single email, sent as drafts to review."},"sequence_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sequence Id","description":"A sequence, which sends on its own."},"mailbox_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mailbox Id","description":"The mailbox, from `GET /v1/me/mailboxes`."},"send_window_start":{"anyOf":[{"type":"string","maxLength":8,"pattern":"^\\d{2}:\\d{2}(:\\d{2})?$"},{"type":"null"}],"title":"Send Window Start","description":"`HH:MM`."},"send_window_end":{"anyOf":[{"type":"string","maxLength":8,"pattern":"^\\d{2}:\\d{2}(:\\d{2})?$"},{"type":"null"}],"title":"Send Window End","description":"`HH:MM`."},"daily_limit":{"anyOf":[{"type":"integer","maximum":500.0,"minimum":1.0},{"type":"null"}],"title":"Daily Limit","description":"Emails a day (1 to 500)."},"re_enrollment_behavior":{"anyOf":[{"type":"string","enum":["skip","continue","restart"]},{"type":"null"}],"title":"Re Enrollment Behavior","description":"`skip` (default), `continue` or `restart`."},"skip_unsubscribe_footer":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Skip Unsubscribe Footer","description":"Send without an unsubscribe footer (default `true`)."},"name":{"anyOf":[{"type":"string","maxLength":200,"minLength":1},{"type":"null"}],"title":"Name","description":"Name."},"send_window_timezone":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"title":"Send Window Timezone","description":"An IANA time zone."},"skip_weekends":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Skip Weekends","description":"Skip weekends."},"send_interval_minutes":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Send Interval Minutes","description":"Minutes between two sends: 0, or 10 and up."},"status":{"anyOf":[{"type":"string","enum":["active","paused","completed","archived"]},{"type":"null"}],"title":"Status","description":"`active` launches a draft or resumes a paused campaign: real emails go out. `paused` stops sending until it is active again. `completed` ends it for good. `archived` hides an ended or draft campaign."}},"additionalProperties":false,"type":"object","title":"CampaignUpdate","description":"Changes to a campaign, or a state change through `status`.","example":{"status":"active"}},"CitationList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/Citation"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Opaque continuation token. Pass back as `?cursor=` to fetch the next page. `null` when `has_more` is false."}},"additionalProperties":false,"type":"object","required":["data","has_more"],"title":"CitationList","description":"Cursor-paginated citations; pass `?sort=rankprompt_score` for top-N views.","example":{"data":[{"ai_overviews_count":0,"analyzed_at":"2026-04-16T09:12:00+00:00","author":"Amanda Furrer","backlink_anchor_text":"adidas Adizero Boston 12","backlink_is_nofollow":false,"backlink_is_sponsored":false,"backlink_is_ugc":false,"backlink_method":"parser","brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","brand_mention_sentiment":"positive","brand_mentioned":true,"categorization_status":"completed","categorized_at":"2026-04-15T10:30:00+00:00","chatgpt_count":3,"chatgpt_search_count":2,"claude_count":0,"claude_search_count":1,"created_at":"2026-04-15T10:00:00+00:00","domain":"runnersworld.com","gemini_count":1,"grok_count":0,"has_backlink":true,"id":"5b9c7e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f","image_url":"https://hips.hearstapps.com/best-running-shoes.jpg","is_actionable":true,"mention_prominence":"headline","muse_count":0,"object":"citation","page_category":"LISTICLE_COMPARISON","page_summary":"Tested picks of road and trail running shoes for every budget.","page_title":"The Best Running Shoes of 2026","perplexity_count":1,"published_at":"2026-05-14T12:00:00+00:00","rankprompt_score":78,"relation":"none","report_ids":["c4f8b6a2-9a17-4e31-92fa-7d1e3b5c8b2a"],"site_name":"Runner's World","site_type":"news","updated_at":"2026-04-15T10:30:00+00:00","url":"https://www.runnersworld.com/gear/a20865766/best-running-shoes/"}],"has_more":false,"object":"list"}},"CitationSeries":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/CitationSeriesPoint"},"type":"array","title":"Data"}},"additionalProperties":false,"type":"object","required":["data"],"title":"CitationSeries","description":"Every point of the series, oldest bucket first.","example":{"data":[{"answers":64,"avg_position":3.2,"bucket":"2026-09-20T00:00:00+00:00","citation_count":17,"cited_answers":12,"key":"news","object":"citation_series_point"}],"object":"list"}},"CitationSeriesPoint":{"properties":{"object":{"type":"string","const":"citation_series_point","title":"Object","description":"Always `citation_series_point`.","default":"citation_series_point"},"bucket":{"type":"string","format":"date-time","title":"Bucket","description":"Start of the day or week counted in `tz`, that date at 00:00 UTC."},"key":{"type":"string","title":"Key","description":"The site type (`classifying` while unknown), relation, domain, page category or URL, per `group`."},"citation_count":{"type":"integer","minimum":0.0,"title":"Citation Count","description":"Citations of the key in the bucket."},"cited_answers":{"type":"integer","minimum":0.0,"title":"Cited Answers","description":"Answers in the bucket that cited the key."},"answers":{"type":"integer","minimum":0.0,"title":"Answers","description":"All answers in the bucket under the filters, cited or not: the bucket's days of `/brands/{brand_id}/prompts/answers/series` summed over the engines."},"avg_position":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Position","description":"Mean place in the answers' source lists."}},"additionalProperties":false,"type":"object","required":["bucket","key","citation_count","cited_answers","answers"],"title":"CitationSeriesPoint","description":"Citations of one key in one day or week.","example":{"answers":64,"avg_position":3.2,"bucket":"2026-09-20T00:00:00+00:00","citation_count":17,"cited_answers":12,"key":"news","object":"citation_series_point"}},"CitationUplift":{"properties":{"object":{"type":"string","const":"citation_uplift","title":"Object","default":"citation_uplift"},"brief_id":{"type":"string","title":"Brief Id"},"published":{"type":"boolean","title":"Published","description":"False until the article is live somewhere.","default":false},"published_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Published At"},"weeks_since_publish":{"type":"integer","minimum":0.0,"title":"Weeks Since Publish","default":0},"before":{"type":"integer","minimum":0.0,"title":"Before","description":"Prompts citing the URL in the reports before it went live.","default":0},"after":{"type":"integer","minimum":0.0,"title":"After","description":"Prompts citing it in the reports since.","default":0},"reports_before":{"type":"integer","minimum":0.0,"title":"Reports Before","default":0},"reports_after":{"type":"integer","minimum":0.0,"title":"Reports After","description":"Zero means no report has run since: there is nothing to judge yet.","default":0},"prompts":{"items":{"type":"string"},"type":"array","title":"Prompts","description":"The prompts that now cite it."},"source_prompts":{"anyOf":[{"items":{"$ref":"#/components/schemas/SourcePromptProgress"},"type":"array"},{"type":"null"}],"title":"Source Prompts","description":"Null when the article was not written against report prompts."},"source_prompts_captured_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Source Prompts Captured At","description":"When those prompts were snapshotted, which is when the article was published."},"source_prompts_recovered":{"type":"integer","minimum":0.0,"title":"Source Prompts Recovered","description":"Engine answers that name the brand again across those prompts.","default":0}},"additionalProperties":false,"type":"object","required":["brief_id"],"title":"CitationUplift","description":"Whether an article moved the citations, measured on the reports around its publish date."},"CitationUpliftList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/CitationUplift"},"type":"array","title":"Data"}},"additionalProperties":false,"type":"object","required":["data"],"title":"CitationUpliftList","description":"Uplift for the briefs asked about. Ids the brand does not own are left out."},"CitedAuthor":{"properties":{"object":{"type":"string","const":"cited_author","title":"Object","description":"Always `cited_author`.","default":"cited_author"},"author_key":{"type":"string","title":"Author Key","description":"The author's key for `/citations/authors/{author_key}/pages`."},"contact_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contact Id","description":"The author's contact; `null` for a byline only."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"},"company":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company"},"linkedin_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Linkedin Url"},"pages":{"type":"integer","minimum":0.0,"title":"Pages","description":"Cited pages they wrote."},"domains":{"items":{"type":"string"},"type":"array","title":"Domains","description":"Sites those pages are on."},"citations":{"type":"integer","minimum":0.0,"title":"Citations","description":"Times the answers cited those pages under the filters."},"prompt_count":{"type":"integer","minimum":0.0,"title":"Prompt Count","description":"Distinct prompts whose answers cited them."},"last_seen":{"type":"string","format":"date-time","title":"Last Seen"}},"additionalProperties":false,"type":"object","required":["author_key","pages","domains","citations","prompt_count","last_seen"],"title":"CitedAuthor","description":"A person who wrote pages the answers cite: a contact a page analysis or contact search found, or a byline."},"CitedAuthorList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/CitedAuthor"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"True when more items exist past this page. Fetch them with a larger `offset`."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of items matching the query, across all pages."},"limit":{"type":"integer","minimum":1.0,"title":"Limit","description":"Page size that was applied."},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of items skipped before this page."}},"additionalProperties":false,"type":"object","required":["data","has_more","total","limit","offset"],"title":"CitedAuthorList","description":"A page of authors, most cited first."},"CitedDomain":{"properties":{"object":{"type":"string","const":"cited_domain","title":"Object","description":"Always `cited_domain`.","default":"cited_domain"},"domain":{"type":"string","title":"Domain","description":"Bare domain."},"site_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Site Type","description":"What the whole site is, an open set (new values can appear): `reddit`, `youtube`, `linkedin`, `wikipedia`, `qa_forum`, `social`, `news`, `reviews`, `reference`, `institutional`, `company`, `marketplace`, `google_place`, `google_product` or `other`; `null` while the site is still being classified."},"relation":{"type":"string","enum":["owned","competitor","none"],"title":"Relation","description":"The page's relation to the brand: `owned` (the brand's own site), `competitor` (the site of an active direct or indirect competitor in the brand's registry) or `none`."},"url_count":{"type":"integer","minimum":0.0,"title":"Url Count","description":"Distinct cited pages on the domain."},"citation_count":{"type":"integer","minimum":0.0,"title":"Citation Count","description":"Citations of the domain's pages in the filtered window."},"first_half_citation_count":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"First Half Citation Count","description":"Citations in the first half of the runs read, runs (a batch of locations, or a report alone) in the order they started, a run that cited nothing under the filters included; with an odd number of runs the middle one counts in neither half. `null` with fewer than two runs."},"second_half_citation_count":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Second Half Citation Count","description":"Citations in the last half of the runs read; `sort=change` and `sort=trend` compare it with the first. `null` with fewer than two runs."},"share":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Share","description":"Percent of all citations in the window."},"prompt_count":{"type":"integer","minimum":0.0,"title":"Prompt Count","description":"Distinct prompts whose answers cited the domain."},"platforms":{"items":{"type":"string"},"type":"array","title":"Platforms","description":"Engines that cited it (an open set)."},"avg_position":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Position","description":"Mean place in the answers' source lists."},"last_seen_at":{"type":"string","format":"date-time","title":"Last Seen At","description":"When an answer last cited the domain."},"analyzed_pages":{"type":"integer","minimum":0.0,"title":"Analyzed Pages","description":"Pages of the domain a paid Analyze read."},"mentioned_pages":{"type":"integer","minimum":0.0,"title":"Mentioned Pages","description":"Analyzed pages that name the brand."},"backlink_pages":{"type":"integer","minimum":0.0,"title":"Backlink Pages","description":"Pages found linking to the brand."},"distinct_brand_count":{"type":"integer","minimum":0.0,"title":"Distinct Brand Count","description":"Brands across Rank Prompt whose answers cite the domain."},"global_citation_count":{"type":"integer","minimum":0.0,"title":"Global Citation Count","description":"Citations of the domain across Rank Prompt."}},"additionalProperties":false,"type":"object","required":["domain","relation","url_count","citation_count","prompt_count","platforms","last_seen_at","analyzed_pages","mentioned_pages","backlink_pages","distinct_brand_count","global_citation_count"],"title":"CitedDomain","description":"The cited pages of one domain rolled up under the Visibility filters.","example":{"analyzed_pages":2,"avg_position":2.9,"backlink_pages":0,"citation_count":88,"distinct_brand_count":14,"domain":"runnersworld.com","first_half_citation_count":40,"global_citation_count":5120,"last_seen_at":"2026-09-20T08:15:00+00:00","mentioned_pages":1,"object":"cited_domain","platforms":["chatgpt","gemini","perplexity"],"prompt_count":19,"relation":"none","second_half_citation_count":48,"share":6.4,"site_type":"news","url_count":6}},"CitedDomainList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/CitedDomain"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"True when more items exist past this page. Fetch them with a larger `offset`."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of items matching the query, across all pages."},"limit":{"type":"integer","minimum":1.0,"title":"Limit","description":"Page size that was applied."},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of items skipped before this page."},"total_citations":{"type":"integer","minimum":0.0,"title":"Total Citations","description":"All citations in the filtered window, across every domain."},"owned_citations":{"type":"integer","minimum":0.0,"title":"Owned Citations","description":"Of those, the citations of the brand's own site."}},"additionalProperties":false,"type":"object","required":["data","has_more","total","limit","offset","total_citations","owned_citations"],"title":"CitedDomainList","description":"A page of cited domains, with the window's totals.","example":{"data":[{"analyzed_pages":2,"avg_position":2.9,"backlink_pages":0,"citation_count":88,"distinct_brand_count":14,"domain":"runnersworld.com","first_half_citation_count":40,"global_citation_count":5120,"last_seen_at":"2026-09-20T08:15:00+00:00","mentioned_pages":1,"object":"cited_domain","platforms":["chatgpt","gemini","perplexity"],"prompt_count":19,"relation":"none","second_half_citation_count":48,"share":6.4,"site_type":"news","url_count":6}],"has_more":false,"limit":100,"object":"list","offset":0,"owned_citations":96,"total":1,"total_citations":1370}},"CitedPage":{"properties":{"object":{"type":"string","const":"cited_page","title":"Object","description":"Always `cited_page`.","default":"cited_page"},"url":{"type":"string","title":"Url","description":"The cited URL, normalized."},"domain":{"type":"string","title":"Domain","description":"Bare domain of the page."},"site_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Site Type","description":"What the whole site is, an open set (new values can appear): `reddit`, `youtube`, `linkedin`, `wikipedia`, `qa_forum`, `social`, `news`, `reviews`, `reference`, `institutional`, `company`, `marketplace`, `google_place`, `google_product` or `other`; `null` while the site is still being classified."},"relation":{"type":"string","enum":["owned","competitor","none"],"title":"Relation","description":"The page's relation to the brand: `owned` (the brand's own site), `competitor` (the site of an active direct or indirect competitor in the brand's registry) or `none`."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"Page title, when known."},"image_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Url","description":"The page's preview image (`og:image` or the engine's thumbnail), `null` until the page is read."},"published_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"format":"date-time","title":"Published At","description":"When the page says it was published, `null` when it does not say or was not read yet."},"author":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Author","description":"The person the page names as its author, `null` when it names none or was not read yet."},"site_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Site Name","description":"The site's own name (`og:site_name`, e.g. `The Verge`), `null` when unknown."},"modified_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"format":"date-time","title":"Modified At","description":"When the page says it was last updated (`article:modified_time`, `og:updated_time` or JSON-LD `dateModified`), `null` when it does not say or was not read yet."},"schema_types":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Schema Types","description":"The Schema.org types the page's JSON-LD declares (e.g. `Article`, `FAQPage`, `Product`), sorted, the first 20 when it declares more; `null` when it declares none or was not read yet."},"citation_count":{"type":"integer","minimum":0.0,"title":"Citation Count","description":"Times the answers cited it in the filtered window."},"prompt_count":{"type":"integer","minimum":0.0,"title":"Prompt Count","description":"Distinct prompts whose answers cited it."},"platforms":{"items":{"type":"string"},"type":"array","title":"Platforms","description":"Engines that cited it (an open set, e.g. `chatgpt`, `perplexity`)."},"platform_counts":{"additionalProperties":{"type":"integer"},"type":"object","title":"Platform Counts","description":"Citations per engine in the filtered window."},"first_seen_at":{"type":"string","format":"date-time","title":"First Seen At","description":"When an answer first cited it in the window."},"last_seen_at":{"type":"string","format":"date-time","title":"Last Seen At","description":"When an answer last cited it in the window."},"avg_position":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Position","description":"Mean place in the answers' source lists (1 is first)."},"report_count":{"type":"integer","minimum":0.0,"title":"Report Count","description":"Reports whose answers cited it."},"share":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Share","description":"Percent of all citations in the window that went to it."},"first_half_citation_count":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"First Half Citation Count","description":"Citations in the first half of the runs read, runs (a batch of locations, or a report alone) in the order they started, a run that cited nothing under the filters included; with an odd number of runs the middle one counts in neither half. `null` with fewer than two runs."},"second_half_citation_count":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Second Half Citation Count","description":"Citations in the last half of the runs read; `sort=change` and `sort=trend` compare it with the first. `null` with fewer than two runs."},"page_category":{"anyOf":[{"type":"string","enum":["HOMEPAGE","PRODUCT_PAGE","LISTICLE_COMPARISON","REVIEW_ROUNDUP","NEWS_ARTICLE","BLOG_POST","GUIDE_TUTORIAL","DOCUMENTATION","DIRECTORY_LISTING","OTHER"]},{"type":"null"}],"title":"Page Category","description":"Same value space as `Citation.page_category`; `null` while uncategorized."},"categorization_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Categorization Status","description":"`completed` once both the site and the page are classified, `pending` while either is being classified, `failed` when either failed for good, `null` before either started."},"analyzed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"format":"date-time","title":"Analyzed At","description":"When a paid Analyze read the page. `null` = not analyzed."},"brand_mentioned":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Brand Mentioned","description":"Whether the page names the brand; `null` until the page is analyzed."},"has_backlink":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Backlink","description":"Whether the page links to the brand: `true` once a link was found, `null` until the page is analyzed."},"outreach_stage":{"anyOf":[{"type":"string","enum":["contact_found","contacted","replied","won"]},{"type":"null"}],"title":"Outreach Stage","description":"Where outreach for the page stands: `contact_found`, `contacted`, `replied`, `won`, or `null`."},"tracked":{"type":"boolean","title":"Tracked","description":"Whether the brand tracks the page, as listed by `GET /v1/brands/{brand_id}/seo-pages`."}},"additionalProperties":false,"type":"object","required":["url","domain","relation","citation_count","prompt_count","platforms","platform_counts","first_seen_at","last_seen_at","report_count","tracked"],"title":"CitedPage","description":"One page the answers cited under the Visibility filters, with its share and change.","example":{"author":"Amanda Furrer","avg_position":2.4,"categorization_status":"completed","citation_count":42,"domain":"runnersworld.com","first_half_citation_count":18,"first_seen_at":"2026-07-02T09:00:00+00:00","image_url":"https://hips.hearstapps.com/best-running-shoes.jpg","last_seen_at":"2026-09-20T08:15:00+00:00","object":"cited_page","page_category":"LISTICLE_COMPARISON","platform_counts":{"chatgpt":30,"perplexity":12},"platforms":["chatgpt","perplexity"],"prompt_count":11,"published_at":"2026-05-14T12:00:00+00:00","relation":"none","report_count":9,"second_half_citation_count":24,"share":3.1,"site_name":"Runner's World","site_type":"news","title":"The Best Running Shoes of 2026","tracked":false,"url":"https://www.runnersworld.com/gear/a20865766/best-running-shoes/"}},"CitedPageList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/CitedPage"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"True when more items exist past this page. Fetch them with a larger `offset`."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of items matching the query, across all pages."},"limit":{"type":"integer","minimum":1.0,"title":"Limit","description":"Page size that was applied."},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of items skipped before this page."}},"additionalProperties":false,"type":"object","required":["data","has_more","total","limit","offset"],"title":"CitedPageList","description":"A page of cited pages in the order asked for.","example":{"data":[{"author":"Amanda Furrer","avg_position":2.4,"categorization_status":"completed","citation_count":42,"domain":"runnersworld.com","first_half_citation_count":18,"first_seen_at":"2026-07-02T09:00:00+00:00","image_url":"https://hips.hearstapps.com/best-running-shoes.jpg","last_seen_at":"2026-09-20T08:15:00+00:00","object":"cited_page","page_category":"LISTICLE_COMPARISON","platform_counts":{"chatgpt":30,"perplexity":12},"platforms":["chatgpt","perplexity"],"prompt_count":11,"published_at":"2026-05-14T12:00:00+00:00","relation":"none","report_count":9,"second_half_citation_count":24,"share":3.1,"site_name":"Runner's World","site_type":"news","title":"The Best Running Shoes of 2026","tracked":false,"url":"https://www.runnersworld.com/gear/a20865766/best-running-shoes/"}],"has_more":false,"limit":100,"object":"list","offset":0,"total":1}},"CitedVideo":{"properties":{"video_id":{"type":"string","title":"Video Id"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"channel_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Channel Title"},"channel_handle":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Channel Handle","description":"The channel's handle, such as `@vitamix`."},"published_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Published At"},"duration_seconds":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Duration Seconds"},"view_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"View Count"},"like_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Like Count"},"citations":{"type":"integer","title":"Citations"},"answers_without_brand":{"type":"integer","title":"Answers Without Brand","description":"Answers that cited the video and did not name the brand."},"prompts":{"items":{"type":"string"},"type":"array","title":"Prompts","description":"Up to five prompts of those answers."},"prompt_count":{"type":"integer","title":"Prompt Count","description":"How many prompts of those answers there are in all.","default":0},"platforms":{"items":{"type":"string"},"type":"array","title":"Platforms"},"last_seen":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Last Seen","description":"When an answer last cited it."}},"additionalProperties":false,"type":"object","required":["video_id","url","title","channel_title","citations","answers_without_brand","prompts","platforms"],"title":"CitedVideo"},"CityEvidence":{"properties":{"city":{"type":"string","maxLength":120,"minLength":1,"title":"City","description":"A city of the plan, as the plan names it."},"photo_ids":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":12},{"type":"null"}],"title":"Photo Ids","description":"Media library images of work done in the city; replaces the city's photos."},"fact":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Fact","description":"A fact of the city only a local would know."}},"additionalProperties":false,"type":"object","required":["city"],"title":"CityEvidence","description":"The owner's evidence of one city of the plan; a field left out stays as it is."},"CityPagePlan":{"properties":{"object":{"type":"string","const":"city_page_plan","title":"Object","description":"Always `city_page_plan`.","default":"city_page_plan"},"id":{"type":"string","title":"Id"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Created At"},"services":{"items":{"type":"string"},"type":"array","title":"Services","description":"The first is the lead service, which the city pages target."},"cities":{"items":{"$ref":"#/components/schemas/CityPlanCity"},"type":"array","title":"Cities"},"hub_path":{"type":"string","title":"Hub Path"},"credits":{"type":"integer","title":"Credits","description":"Credits the search volumes cost when the plan was built."},"sitemap_read":{"type":"boolean","title":"Sitemap Read"},"refreshed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Refreshed At"},"gbp_linked":{"type":"boolean","title":"Gbp Linked","description":"Whether a Business Profile location is linked, so reviews are counted."},"counts":{"$ref":"#/components/schemas/CityPlanCounts"},"pages":{"items":{"$ref":"#/components/schemas/CityPlanPage"},"type":"array","title":"Pages"}},"additionalProperties":false,"type":"object","required":["id","services","cities","hub_path","credits","sitemap_read","gbp_linked","counts","pages"],"title":"CityPagePlan","description":"The brand's city page plan: its services and cities, and a page per city and per service in each city."},"CityPagePlanBuild":{"properties":{"services":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":10},{"type":"null"}],"title":"Services","description":"Left out: the linked profiles' main category and services."},"cities":{"anyOf":[{"items":{"$ref":"#/components/schemas/CityPlanCityInput"},"type":"array","maxItems":20},{"type":"null"}],"title":"Cities","description":"Left out: the cities of the linked locations and their service areas, and the brand's places."}},"additionalProperties":false,"type":"object","title":"CityPagePlanBuild"},"CityPagePlanShare":{"properties":{"object":{"type":"string","const":"city_page_plan_share","title":"Object","default":"city_page_plan_share"},"id":{"type":"string","title":"Id"},"version_id":{"type":"string","title":"Version Id","description":"The published document version the link opens."},"url":{"type":"string","title":"Url","description":"The public link, on the account's own domain when it has one."},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Expires At"},"has_password":{"type":"boolean","title":"Has Password"},"is_existing":{"type":"boolean","title":"Is Existing"}},"additionalProperties":false,"type":"object","required":["id","version_id","url","has_password","is_existing"],"title":"CityPagePlanShare","description":"A public link to the city page plan, under the account's branding; sharing the same plan again refreshes it."},"CityPagePlanShareCreate":{"properties":{"expiration_days":{"type":"integer","maximum":365.0,"minimum":1.0,"title":"Expiration Days","description":"Days the link opens for.","default":30},"password":{"anyOf":[{"type":"string","maxLength":128,"minLength":4},{"type":"null"}],"title":"Password","description":"Ask viewers for it."}},"additionalProperties":false,"type":"object","title":"CityPagePlanShareCreate","description":"How long the link opens and an optional password."},"CityPlanCity":{"properties":{"name":{"type":"string","title":"Name"},"zones":{"items":{"type":"string"},"type":"array","title":"Zones","description":"Nearby areas named on the city page."},"has_location":{"type":"boolean","title":"Has Location","description":"The business has premises there: its pages are `location`, else `service_area`."},"photos":{"items":{"$ref":"#/components/schemas/CityPlanPhoto"},"type":"array","title":"Photos","description":"Media library photos of work there."},"fact":{"type":"string","title":"Fact","description":"A fact of the city the owner wrote.","default":""},"reviews":{"type":"integer","title":"Reviews","description":"Business Profile reviews naming the city; 0 without a linked location.","default":0}},"additionalProperties":false,"type":"object","required":["name","has_location"],"title":"CityPlanCity","description":"A city of the plan with the owner's evidence of it, which counts for every page of the city."},"CityPlanCityInput":{"properties":{"name":{"type":"string","maxLength":120,"minLength":1,"title":"Name"},"zones":{"items":{"type":"string"},"type":"array","maxItems":20,"title":"Zones","description":"Nearby areas served from the city."},"has_location":{"type":"boolean","title":"Has Location","description":"The business has premises in the city.","default":false}},"additionalProperties":false,"type":"object","required":["name"],"title":"CityPlanCityInput"},"CityPlanCounts":{"properties":{"pages":{"type":"integer","title":"Pages"},"ready":{"type":"integer","title":"Ready"},"needs_evidence":{"type":"integer","title":"Needs Evidence"},"in_progress":{"type":"integer","title":"In Progress","description":"Being written, proposed or publishing."},"live":{"type":"integer","title":"Live"},"covered":{"type":"integer","title":"Covered"}},"additionalProperties":false,"type":"object","required":["pages","ready","needs_evidence","in_progress","live","covered"],"title":"CityPlanCounts"},"CityPlanPage":{"properties":{"id":{"type":"string","title":"Id","description":"The page's id in Website autopilot."},"page_type":{"type":"string","enum":["location","service_area","location_hub"],"title":"Page Type"},"title":{"type":"string","title":"Title"},"path":{"type":"string","title":"Path","description":"Where the page goes on the site, as the writer places a page of its type."},"city":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"City","description":"Null for the hub."},"keyword":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Keyword","description":"The exact search the page answers."},"volume":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Volume","description":"Monthly searches of `keyword`."},"stage":{"type":"string","enum":["needs_evidence","ready","covered","dismissed","generating","proposed","publishing","not_answering","live","indexed"],"title":"Stage"},"missing":{"items":{"type":"string","enum":["own_facts","demand","competitor","competitor_prompt","questions","amount","city_reviews","city_photos","city_fact","brand_facts"]},"type":"array","title":"Missing","description":"What it waits for: two of `city_reviews`, `city_photos` and `city_fact`, and `brand_facts` when the brand has no facts to write from."},"overridden":{"type":"boolean","title":"Overridden","description":"Made ready by hand without enough evidence, recorded.","default":false},"existing_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Existing Url","description":"The page the sitemap shows for it (`covered`)."},"live_urls":{"items":{"type":"string"},"type":"array","title":"Live Urls","description":"Where it went live, one per language."}},"additionalProperties":false,"type":"object","required":["id","page_type","title","path","stage"],"title":"CityPlanPage","description":"A page of the plan, a Website autopilot new page: written by a wave of new pages once it is ready."},"CityPlanPhoto":{"properties":{"id":{"type":"string","title":"Id","description":"The media library item."},"url":{"type":"string","title":"Url"},"alt":{"type":"string","title":"Alt","default":""}},"additionalProperties":false,"type":"object","required":["id","url"],"title":"CityPlanPhoto"},"ClientReport":{"properties":{"object":{"type":"string","const":"client_report","title":"Object","description":"Always `client_report`.","default":"client_report"},"id":{"type":"string","title":"Id"},"brand_id":{"type":"string","title":"Brand Id"},"title":{"type":"string","title":"Title"},"template_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Template Key"},"account_template_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Account Template Id"},"report_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Report Id","description":"The visibility report it is anchored to, if any."},"tracker_market_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tracker Market Id","description":"The market (place) it reads. None reads the anchored run as a whole, every market of it."},"audit_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Audit Id","description":"The brand audit it is anchored to, if any."},"page_spec":{"additionalProperties":true,"type":"object","title":"Page Spec","description":"The sheets in order, each with up to four blocks (`id`, `block_id`, `enabled`, `width`, `config`, `narrative_key`), plus the report's `identity` and `language`."},"narrative":{"additionalProperties":true,"type":"object","title":"Narrative","description":"The sentences written for blocks, by narrative key."},"status":{"type":"string","enum":["draft","published","archived"],"title":"Status"},"current_version_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Current Version Id"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Created At"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Updated At"}},"additionalProperties":false,"type":"object","required":["id","brand_id","title","page_spec","narrative","status"],"title":"ClientReport","description":"A client report as it stands, draft included: its sheets, blocks and the sentences written for them."},"ClientReportCreate":{"properties":{"brand_id":{"type":"string","title":"Brand Id","description":"The client brand it reports on."},"title":{"type":"string","maxLength":120,"minLength":1,"title":"Title"},"template_key":{"anyOf":[{"type":"string","maxLength":60},{"type":"null"}],"title":"Template Key","description":"A house template."},"account_template_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Account Template Id","description":"One of the account's own templates."},"start_blank":{"type":"boolean","title":"Start Blank","description":"Start with no sheets instead of a template.","default":false},"report_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Report Id","description":"Anchor it to one visibility report of the brand."},"tracker_market_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tracker Market Id","description":"Keep it on one market (place) of the brand: it reads that place's run. Omitted with a `report_id`, it reads that report's market; `null` reads the anchored run as a whole; with neither, the brand's latest run."},"audit_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Audit Id","description":"Anchor it to one brand audit of the brand."},"identity":{"anyOf":[{"type":"string","enum":["agency","client"]},{"type":"null"}],"title":"Identity","description":"Whose branding it wears: `agency` or `client`."},"language":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}],"title":"Language","description":"Its language; the brand's by default."}},"additionalProperties":false,"type":"object","required":["brand_id","title"],"title":"ClientReportCreate","description":"Start a client report from a house template, an account template, the account's default, or blank.","example":{"brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","template_key":"monthly","title":"Solace Health, October AI visibility"}},"ClientReportDelivery":{"properties":{"object":{"type":"string","const":"client_report_delivery","title":"Object","default":"client_report_delivery"},"delivered":{"type":"boolean","title":"Delivered"},"status":{"type":"string","title":"Status","description":"The delivery's state after the send."}},"additionalProperties":false,"type":"object","required":["delivered","status"],"title":"ClientReportDelivery","description":"What happened to the client email of a version held for review."},"ClientReportEdited":{"properties":{"object":{"type":"string","const":"client_report","title":"Object","description":"Always `client_report`.","default":"client_report"},"id":{"type":"string","title":"Id"},"brand_id":{"type":"string","title":"Brand Id"},"title":{"type":"string","title":"Title"},"template_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Template Key"},"account_template_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Account Template Id"},"report_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Report Id","description":"The visibility report it is anchored to, if any."},"tracker_market_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tracker Market Id","description":"The market (place) it reads. None reads the anchored run as a whole, every market of it."},"audit_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Audit Id","description":"The brand audit it is anchored to, if any."},"page_spec":{"additionalProperties":true,"type":"object","title":"Page Spec","description":"The sheets in order, each with up to four blocks (`id`, `block_id`, `enabled`, `width`, `config`, `narrative_key`), plus the report's `identity` and `language`."},"narrative":{"additionalProperties":true,"type":"object","title":"Narrative","description":"The sentences written for blocks, by narrative key."},"status":{"type":"string","enum":["draft","published","archived"],"title":"Status"},"current_version_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Current Version Id"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Created At"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Updated At"},"added_blocks":{"items":{"type":"string"},"type":"array","title":"Added Blocks","description":"Ids of the blocks the operations added."}},"additionalProperties":false,"type":"object","required":["id","brand_id","title","page_spec","narrative","status","added_blocks"],"title":"ClientReportEdited","description":"The report after the edits, and the blocks they added."},"ClientReportFacts":{"properties":{"object":{"type":"string","const":"client_report_facts","title":"Object","default":"client_report_facts"},"document_id":{"type":"string","title":"Document Id"},"facts":{"additionalProperties":true,"type":"object","title":"Facts","description":"Per block id: `available`, its `data`, and why it is left off the paper when it has none."}},"additionalProperties":false,"type":"object","required":["document_id","facts"],"title":"ClientReportFacts","description":"What each block of the report would show today; publishing freezes its own snapshot."},"ClientReportList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/ClientReportSummary"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"True when more items exist past this page. Fetch them with a larger `offset`."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of items matching the query, across all pages."},"limit":{"type":"integer","minimum":1.0,"title":"Limit","description":"Page size that was applied."},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of items skipped before this page."}},"additionalProperties":false,"type":"object","required":["data","has_more","total","limit","offset"],"title":"ClientReportList","description":"A page of the account's client reports."},"ClientReportShare":{"properties":{"object":{"type":"string","const":"client_report_share","title":"Object","default":"client_report_share"},"id":{"type":"string","title":"Id"},"version_id":{"type":"string","title":"Version Id"},"url":{"type":"string","title":"Url","description":"The public link, on the account's own domain when it has one."},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Expires At"},"has_password":{"type":"boolean","title":"Has Password"},"is_existing":{"type":"boolean","title":"Is Existing","description":"True when the version already had a link, now refreshed."}},"additionalProperties":false,"type":"object","required":["id","version_id","url","has_password","is_existing"],"title":"ClientReportShare","description":"The link to the version; sharing the same version again refreshes its link."},"ClientReportShareCreate":{"properties":{"expiration_days":{"type":"integer","maximum":365.0,"minimum":1.0,"title":"Expiration Days","description":"Days the link opens for.","default":30},"password":{"anyOf":[{"type":"string","maxLength":128,"minLength":4},{"type":"null"}],"title":"Password","description":"Ask viewers for it."}},"additionalProperties":false,"type":"object","title":"ClientReportShareCreate","description":"A public link to one published version."},"ClientReportSummary":{"properties":{"object":{"type":"string","const":"client_report","title":"Object","description":"Always `client_report`.","default":"client_report"},"id":{"type":"string","title":"Id"},"brand_id":{"type":"string","title":"Brand Id"},"brand_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brand Name"},"title":{"type":"string","title":"Title"},"template_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Template Key","description":"The house template it started from."},"account_template_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Account Template Id","description":"The account template it started from."},"status":{"type":"string","enum":["draft","published","archived"],"title":"Status","description":"`draft`, `published` or `archived`."},"current_version_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Current Version Id","description":"The version the client sees."},"current_version":{"anyOf":[{"$ref":"#/components/schemas/ClientReportVersionRef"},{"type":"null"}]},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Created At"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Updated At"}},"additionalProperties":false,"type":"object","required":["id","brand_id","title","status"],"title":"ClientReportSummary","description":"A client report as the list shows it, without its sheets."},"ClientReportUpdate":{"properties":{"title":{"anyOf":[{"type":"string","maxLength":120,"minLength":1},{"type":"null"}],"title":"Title"},"operations":{"items":{"additionalProperties":true,"type":"object"},"type":"array","maxItems":100,"title":"Operations","description":"Applied in order: `add {block_id, sheet?, position?, at?, config?}`, `remove {block}`, `remove_sheet {sheet}`, `move {block, sheet, position?}`, `move_sheet {sheet, to}`, `toggle {block, enabled}`, `config {block, values}` (a null value removes the key), `width {block, width}`, `sentence {block, text}`. Sheets and positions count from 1; blocks are named by their `id`."}},"additionalProperties":false,"type":"object","title":"ClientReportUpdate","description":"Rename the report and apply edit operations in order, all or none.","example":{"operations":[{"at":2,"block_id":"section_opener","config":{"title":"Where you stand"},"op":"add"},{"block":"b2","op":"sentence","text":"Up six points, and ahead of two rivals."}]}},"ClientReportVersion":{"properties":{"object":{"type":"string","const":"client_report_version","title":"Object","default":"client_report_version"},"id":{"type":"string","title":"Id"},"document_id":{"type":"string","title":"Document Id"},"version_number":{"type":"integer","title":"Version Number"},"published_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Published At"},"render_state":{"type":"string","enum":["waiting","ready","failed"],"title":"Render State","description":"Its PDF: `waiting`, `ready` or `failed`."},"render_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Render Error"},"delivery_state":{"type":"string","enum":["draft","ready_to_send","sent"],"title":"Delivery State","description":"`draft`, `ready_to_send` (held for review) or `sent`."}},"additionalProperties":false,"type":"object","required":["id","document_id","version_number","render_state","delivery_state"],"title":"ClientReportVersion","description":"A published version: what the client sees, frozen."},"ClientReportVersionRef":{"properties":{"version_number":{"type":"integer","title":"Version Number"},"published_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Published At"},"render_state":{"type":"string","enum":["waiting","ready","failed"],"title":"Render State","description":"Its PDF: `waiting`, `ready` or `failed`."},"delivery_state":{"type":"string","enum":["draft","ready_to_send","sent"],"title":"Delivery State","description":"`draft`, `ready_to_send` (held for review) or `sent`."}},"additionalProperties":false,"type":"object","required":["version_number","render_state","delivery_state"],"title":"ClientReportVersionRef","description":"The published version a client report points at."},"CmsConnection":{"properties":{"object":{"type":"string","const":"cms_connection","title":"Object","description":"Always `cms_connection`.","default":"cms_connection"},"id":{"type":"string","title":"Id","description":"Connection id (UUID). Pass as `target_id` when publishing."},"brand_id":{"type":"string","title":"Brand Id","description":"Owning brand id (UUID)."},"provider":{"type":"string","title":"Provider","description":"CMS platform, an open set (new values can appear): `wordpress`, `wordpress_com` (a site hosted on WordPress.com), `ghost`, `shopify`, `webflow`, `wix`, `github` (a connected repository whose blog the article is written into, live once its pull request merges) or a `webhook` destination."},"status":{"type":"string","enum":["connected","disconnected","error"],"title":"Status","description":"Credential health. `connected` when we last reached the site, `error` when a check or publish failed, `disconnected` when it was never established."},"site_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Site Url","description":"Where the connection publishes: the site, the Shopify blog or the Webflow collection. For a `webhook` only its host, since the full URL works as a credential. For `github`, the repository."},"username":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Username","description":"Username the stored credential belongs to."},"has_credentials":{"type":"boolean","title":"Has Credentials","description":"True when a secret is stored for this connection. The secret itself is never returned."},"default_status":{"anyOf":[{"type":"string","enum":["ask","draft"]},{"type":"null"}],"title":"Default Status","description":"What the brand's owner chose for every send to this site: `draft` when each article should land as a draft for someone to review, `ask` when it is chosen per publish. This API does not apply it for you: `publish_status` still defaults to `publish`, so send `publish_status: draft` when this says `draft`. Null for a provider without this choice (`github`, `webhook`) and for the hosted blog."},"settings":{"$ref":"#/components/schemas/CmsConnectionSettings","description":"The owner's other publishing choices for this site, read only. Credentials are never included."},"last_synced_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Last Synced At","description":"Last time the credentials were confirmed working. Only advances on a successful check."},"last_error_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Error Code","description":"Why the connection needs its owner, or null when it works. An open set (new values can appear): `token_expired`, `scope_missing`, `not_selected`, `auth_failed`, `permission_missing`, `site_unreachable`, `host_moved`, `app_uninstalled`, `rate_limited`, `vendor_down`."},"last_error_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Last Error At","description":"When `last_error_code` was set; null while the connection works."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the connection was created."},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"When the connection was last modified."}},"additionalProperties":false,"type":"object","required":["id","brand_id","provider","status","has_credentials","created_at","updated_at"],"title":"CmsConnection","description":"A connected CMS that a brand's articles can be published to."},"CmsConnectionCheck":{"properties":{"object":{"type":"string","const":"cms_connection_check","title":"Object","description":"Always `cms_connection_check`.","default":"cms_connection_check"},"connection_id":{"type":"string","title":"Connection Id","description":"Connection that was checked (UUID)."},"ok":{"type":"boolean","title":"Ok","description":"True when the credentials still work and the site is reachable."},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Why the check failed, when `ok` is false."},"status":{"type":"string","enum":["connected","disconnected","error"],"title":"Status","description":"The connection's `status` after the check."}},"additionalProperties":false,"type":"object","required":["connection_id","ok","status"],"title":"CmsConnectionCheck","description":"Outcome of re-verifying a stored connection against the live site."},"CmsConnectionCreate":{"properties":{"provider":{"type":"string","const":"wordpress","title":"Provider","description":"CMS platform to connect through the API. Only `wordpress` today; Ghost, Shopify, Webflow, GitHub and webhook destinations are connected from the dashboard, Wix by installing our app on the site from the dashboard and WordPress.com by approving access on WordPress.com from the dashboard, then all are listed here.","default":"wordpress"},"credentials":{"$ref":"#/components/schemas/WordPressCredentials","description":"Credentials for the site. Verified against the live site before anything is stored."}},"additionalProperties":false,"type":"object","required":["credentials"],"title":"CmsConnectionCreate","description":"Connect a CMS to a brand, or replace the brand's existing connection for that provider."},"CmsConnectionList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/CmsConnection"},"type":"array","title":"Data"}},"additionalProperties":false,"type":"object","required":["data"],"title":"CmsConnectionList","description":"A brand's CMS connections, bounded to one per provider and therefore not paginated."},"CmsConnectionSettings":{"properties":{"featured_image":{"anyOf":[{"type":"string","enum":["featured_and_body","featured_only","body_only"]},{"type":"null"}],"title":"Featured Image","description":"Where the article's featured image goes: `featured_and_body` (the CMS's featured image and the top of the body), `featured_only` or `body_only`. Null where the CMS has no featured image of its own."},"author_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Author Id","description":"`wordpress` and `wordpress_com`: the site user posts are credited to, or null for the connected user. Null for other providers."},"category_ids":{"anyOf":[{"items":{"anyOf":[{"type":"integer"},{"type":"string"}]},"type":"array"},{"type":"null"}],"title":"Category Ids","description":"`wordpress` and `wordpress_com` (numeric ids) and `wix` (GUIDs): the categories every post goes in, empty for the site's default category. Null for other providers."},"primary_tag":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Primary Tag","description":"`ghost`: the tag every post leads with, or null for the article's first tag. Null for other providers."}},"additionalProperties":false,"type":"object","title":"CmsConnectionSettings","description":"The owner's choices that every publish to the site follows, set in the app's Integrations."},"CommunityDraft":{"properties":{"reply":{"type":"string","title":"Reply","description":"The reply text."},"mentions_brand":{"type":"boolean","title":"Mentions Brand","description":"Whether the reply names the brand."},"disclosure":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Disclosure","description":"The disclosure line to keep when it names the brand."},"language":{"type":"string","title":"Language","description":"The language it is written in."},"rules_risk":{"type":"string","enum":["low","medium","high"],"title":"Rules Risk","description":"How likely the community's rules frown on it: `low`, `medium`, `high`."},"rules_notes":{"type":"string","title":"Rules Notes","description":"Why."},"tone":{"type":"string","enum":["helpful","expert","casual"],"title":"Tone"},"length":{"type":"string","enum":["short","medium","long"],"title":"Length"}},"additionalProperties":false,"type":"object","required":["reply","mentions_brand","language","rules_risk","rules_notes","tone","length"],"title":"CommunityDraft","description":"The latest reply the model proposed; it is never posted, the user copies it."},"CommunityDraftRequest":{"properties":{"tone":{"type":"string","enum":["helpful","expert","casual"],"title":"Tone","default":"helpful"},"length":{"type":"string","enum":["short","medium","long"],"title":"Length","default":"medium"}},"additionalProperties":false,"type":"object","title":"CommunityDraftRequest","description":"How the reply should read."},"CommunitySearch":{"properties":{"object":{"type":"string","const":"community_search","title":"Object","description":"Always `community_search`.","default":"community_search"},"id":{"type":"string","title":"Id"},"keyword":{"type":"string","title":"Keyword"},"market":{"type":"string","title":"Market","description":"The country and language searched, e.g. `United States/English`."},"fetched_at":{"type":"string","format":"date-time","title":"Fetched At"},"results":{"items":{"$ref":"#/components/schemas/CommunitySearchResult"},"type":"array","title":"Results"}},"additionalProperties":false,"type":"object","required":["id","keyword","market","fetched_at","results"],"title":"CommunitySearch","description":"The keyword's saved search with the threads it found."},"CommunitySearchRequest":{"properties":{"keyword":{"type":"string","maxLength":120,"minLength":2,"title":"Keyword"},"country":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Country","description":"English country name to search Google in, e.g. `Argentina`. Brand's market by default."},"language":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}],"title":"Language","description":"Language of the results, e.g. `Spanish`. With a country and no language, that country's language."}},"additionalProperties":false,"type":"object","required":["keyword"],"title":"CommunitySearchRequest","description":"A keyword to search Google for, in the brand's market unless `country` or `language` says otherwise.","example":{"keyword":"best crm for agencies"}},"CommunitySearchResult":{"properties":{"url":{"type":"string","title":"Url"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"snippet":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Snippet"},"source_type":{"type":"string","enum":["reddit","qa_forum","linkedin"],"title":"Source Type"},"group_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Group Key"},"position":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Position","description":"Its place on Google's page."}},"additionalProperties":false,"type":"object","required":["url","source_type"],"title":"CommunitySearchResult","description":"One thread Google ranks for the keyword."},"CommunityStatusCounts":{"properties":{"open":{"type":"integer","title":"Open"},"drafted":{"type":"integer","title":"Drafted"},"replied":{"type":"integer","title":"Replied"},"ignored":{"type":"integer","title":"Ignored"}},"additionalProperties":false,"type":"object","required":["open","drafted","replied","ignored"],"title":"CommunityStatusCounts","description":"How many threads sit in each status under the list's other filters."},"CommunityThread":{"properties":{"object":{"type":"string","const":"community_thread","title":"Object","description":"Always `community_thread`.","default":"community_thread"},"id":{"type":"string","title":"Id"},"url":{"type":"string","title":"Url"},"source_type":{"type":"string","enum":["reddit","qa_forum","linkedin"],"title":"Source Type","description":"`reddit`, `qa_forum` or `linkedin`."},"group_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Group Key","description":"The subreddit or forum, when known."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"snippet":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Snippet"},"origin":{"type":"string","enum":["citation","search","keyword"],"title":"Origin","description":"How it was added: `citation`, `search` or `keyword`."},"status":{"type":"string","enum":["open","drafted","replied","ignored"],"title":"Status","description":"`open`, `drafted`, `replied` or `ignored`."},"context":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Context","description":"The thread's text a draft is written from."},"context_source":{"anyOf":[{"type":"string","enum":["pasted","search_result","web_search"]},{"type":"null"}],"title":"Context Source","description":"`pasted`, `search_result`, or `web_search` (a model's reading of the thread, approximate)."},"draft":{"anyOf":[{"$ref":"#/components/schemas/CommunityDraft"},{"type":"null"}]},"drafted_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"format":"date-time","title":"Drafted At"},"reply_permalink":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reply Permalink","description":"The link to the reply once posted."},"replied_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"format":"date-time","title":"Replied At"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"},"citations":{"type":"integer","minimum":0.0,"title":"Citations","description":"Times the answers cited the thread."},"prompt_count":{"type":"integer","minimum":0.0,"title":"Prompt Count"},"platforms":{"items":{"type":"string"},"type":"array","title":"Platforms","description":"Engines that cited it (an open set)."},"last_cited":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"format":"date-time","title":"Last Cited"}},"additionalProperties":false,"type":"object","required":["id","url","source_type","origin","status","created_at","updated_at","citations","prompt_count","platforms"],"title":"CommunityThread","description":"A thread the brand chose to answer, with how often the answers cite it."},"CommunityThreadInput":{"properties":{"url":{"type":"string","title":"Url","description":"A Reddit post, forum thread or LinkedIn post URL."},"title":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Title"},"snippet":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Snippet"}},"additionalProperties":false,"type":"object","required":["url"],"title":"CommunityThreadInput","description":"One thread to add."},"CommunityThreadList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/CommunityThread"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"True when more items exist past this page. Fetch them with a larger `offset`."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of items matching the query, across all pages."},"limit":{"type":"integer","minimum":1.0,"title":"Limit","description":"Page size that was applied."},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of items skipped before this page."},"status_counts":{"$ref":"#/components/schemas/CommunityStatusCounts"}},"additionalProperties":false,"type":"object","required":["data","has_more","total","limit","offset","status_counts"],"title":"CommunityThreadList","description":"A page of threads, the most cited first."},"CommunityThreadUpdate":{"properties":{"status":{"anyOf":[{"type":"string","enum":["open","drafted","replied","ignored"]},{"type":"null"}],"title":"Status"},"context":{"anyOf":[{"type":"string","maxLength":20000},{"type":"null"}],"title":"Context","description":"The thread's text; empty clears it."},"reply_permalink":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reply Permalink","description":"The posted reply's link."}},"additionalProperties":false,"type":"object","title":"CommunityThreadUpdate","description":"Move a thread, paste its text, or record the reply's link (which marks it replied).","example":{"status":"ignored"}},"CommunityThreadsAdd":{"properties":{"items":{"items":{"$ref":"#/components/schemas/CommunityThreadInput"},"type":"array","maxItems":50,"minItems":1,"title":"Items"},"origin":{"type":"string","enum":["citation","search","keyword"],"title":"Origin","description":"`citation` (a thread the answers cited or any thread URL), `search` (from a community search, which keeps what Google showed) or `keyword` (from a tracked keyword's results)."}},"additionalProperties":false,"type":"object","required":["items","origin"],"title":"CommunityThreadsAdd","description":"Threads to add to the brand's Community.","example":{"items":[{"url":"https://www.reddit.com/r/sales/comments/1f2g3h4/best_crm_for_a_small_agency"}],"origin":"citation"}},"CommunityThreadsAdded":{"properties":{"object":{"type":"string","const":"community_threads_added","title":"Object","default":"community_threads_added"},"added":{"type":"integer","minimum":0.0,"title":"Added"},"rejected":{"items":{"type":"string"},"type":"array","title":"Rejected","description":"URLs that are not a Reddit post, a forum thread or a LinkedIn post."}},"additionalProperties":false,"type":"object","required":["added","rejected"],"title":"CommunityThreadsAdded","description":"What was added and what was refused."},"Competitor":{"properties":{"object":{"type":"string","const":"competitor","title":"Object","description":"Always `competitor`.","default":"competitor"},"id":{"type":"string","title":"Id","description":"Stable competitor identifier (UUID)."},"brand_id":{"type":"string","title":"Brand Id","description":"Owning brand id (UUID)."},"name":{"type":"string","title":"Name","description":"Canonical display name of the entity."},"aliases":{"items":{"type":"string"},"type":"array","title":"Aliases","description":"Alternative names that resolve to this entity."},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain","description":"Bare domain (e.g. `nike.com`)."},"website":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Website","description":"Normalised website URL."},"category":{"anyOf":[{"type":"string","enum":["direct_competitor","indirect_competitor","ai_platform","publisher","other","my_brand"]},{"type":"null"}],"title":"Category","description":"Entity classification. One of `direct_competitor`, `indirect_competitor`, `ai_platform`, `publisher`, `other`, or `my_brand`."},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"Short explanation of why this entity is classified as a competitor."},"tags":{"items":{"type":"string"},"type":"array","title":"Tags","description":"Labels the team gave this entity."},"mention_count":{"type":"integer","minimum":0.0,"title":"Mention Count","description":"Total mentions across the brand's reports.","default":0},"report_count":{"type":"integer","minimum":0.0,"title":"Report Count","description":"Number of reports this entity appeared in.","default":0},"first_seen_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"First Seen At","description":"ISO-8601 timestamp of the first report this entity appeared in."},"last_seen_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Last Seen At","description":"ISO-8601 timestamp of the most recent report this entity appeared in."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"ISO-8601 timestamp when the entity was first registered."},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"ISO-8601 timestamp when the entity was last updated."}},"additionalProperties":false,"type":"object","required":["id","brand_id","name","created_at","updated_at"],"title":"Competitor","description":"A canonical entity in the brand's cross-report competitor directory.","example":{"aliases":["Nike Running","Nike Inc."],"brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","category":"direct_competitor","created_at":"2026-01-05T09:00:00+00:00","domain":"nike.com","first_seen_at":"2026-01-05T09:00:00+00:00","id":"018e7c2e-33ab-7df1-b1cd-2ac3a8f9112d","last_seen_at":"2026-04-18T09:00:00+00:00","mention_count":42,"name":"Nike","object":"competitor","reason":"Sells running shoes to the same buyers.","report_count":7,"tags":["Retail"],"updated_at":"2026-04-18T09:00:00+00:00","website":"https://www.nike.com"}},"CompetitorDomain":{"properties":{"object":{"type":"string","const":"competitor_domain","title":"Object","default":"competitor_domain"},"domain":{"type":"string","title":"Domain","description":"The registrable domain kept."},"added":{"type":"boolean","title":"Added","description":"False when the brand already had it.","default":true}},"type":"object","required":["domain"],"title":"CompetitorDomain"},"CompetitorDomainCreate":{"properties":{"domain":{"type":"string","maxLength":300,"minLength":3,"title":"Domain","examples":["salesforce.com"]}},"type":"object","required":["domain"],"title":"CompetitorDomainCreate","description":"A competitor site to compare against in Google, by address or domain."},"CompetitorDuplicateGroup":{"properties":{"object":{"type":"string","const":"competitor_duplicate_group","title":"Object","description":"Always `competitor_duplicate_group`.","default":"competitor_duplicate_group"},"reason":{"type":"string","enum":["domain","name"],"title":"Reason","description":"`domain` when they share a domain, `name` when their names match once case, accents and company suffixes go."},"key":{"type":"string","title":"Key","description":"The shared domain or the folded name."},"competitors":{"items":{"$ref":"#/components/schemas/Competitor"},"type":"array","title":"Competitors","description":"The entities of the group, most mentioned first. Merge them with `POST /v1/brands/{brand_id}/competitors/merges`."}},"additionalProperties":false,"type":"object","required":["reason","key","competitors"],"title":"CompetitorDuplicateGroup","description":"Competitors that look like one company, to merge into one.","example":{"competitors":[{"aliases":["Nike Running","Nike Inc."],"brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","category":"direct_competitor","created_at":"2026-01-05T09:00:00+00:00","domain":"nike.com","first_seen_at":"2026-01-05T09:00:00+00:00","id":"018e7c2e-33ab-7df1-b1cd-2ac3a8f9112d","last_seen_at":"2026-04-18T09:00:00+00:00","mention_count":42,"name":"Nike","object":"competitor","reason":"Sells running shoes to the same buyers.","report_count":7,"tags":["Retail"],"updated_at":"2026-04-18T09:00:00+00:00","website":"https://www.nike.com"}],"key":"nike","object":"competitor_duplicate_group","reason":"name"}},"CompetitorDuplicates":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/CompetitorDuplicateGroup"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"True when more items exist past this page. Fetch them with a larger `offset`."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of items matching the query, across all pages."},"limit":{"type":"integer","minimum":1.0,"title":"Limit","description":"Page size that was applied."},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of items skipped before this page."}},"additionalProperties":false,"type":"object","required":["data","has_more","total","limit","offset"],"title":"CompetitorDuplicates","description":"A page of the groups of likely duplicates in the directory, domain matches first.","example":{"data":[{"competitors":[{"aliases":["Nike Running","Nike Inc."],"brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","category":"direct_competitor","created_at":"2026-01-05T09:00:00+00:00","domain":"nike.com","first_seen_at":"2026-01-05T09:00:00+00:00","id":"018e7c2e-33ab-7df1-b1cd-2ac3a8f9112d","last_seen_at":"2026-04-18T09:00:00+00:00","mention_count":42,"name":"Nike","object":"competitor","reason":"Sells running shoes to the same buyers.","report_count":7,"tags":["Retail"],"updated_at":"2026-04-18T09:00:00+00:00","website":"https://www.nike.com"}],"key":"nike","object":"competitor_duplicate_group","reason":"name"}],"has_more":false,"limit":20,"object":"list","offset":0,"total":1}},"CompetitorFacets":{"properties":{"categories":{"additionalProperties":{"type":"integer"},"propertyNames":{"enum":["direct_competitor","indirect_competitor","ai_platform","publisher","other"]},"type":"object","title":"Categories","description":"Entities per category under the `tag` and `search` filters, every category present (0 when none): what `category=<key>` would list."},"tags":{"items":{"$ref":"#/components/schemas/CompetitorTagCount"},"type":"array","title":"Tags","description":"Every tag on an entity under the `category` and `search` filters, alphabetical."}},"additionalProperties":false,"type":"object","required":["categories","tags"],"title":"CompetitorFacets","description":"Entities per category and per tag, each count under every filter but its own."},"CompetitorList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/Competitor"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"True when more items exist past this page. Fetch them with a larger `offset`."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of items matching the query, across all pages."},"limit":{"type":"integer","minimum":1.0,"title":"Limit","description":"Page size that was applied."},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of items skipped before this page."},"facets":{"$ref":"#/components/schemas/CompetitorFacets","description":"Entities per category and per tag, to build filters from."}},"additionalProperties":false,"type":"object","required":["data","has_more","total","limit","offset","facets"],"title":"CompetitorList","description":"A page of the competitor directory, with the facets of its filters.","example":{"data":[{"aliases":["Nike Running","Nike Inc."],"brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","category":"direct_competitor","created_at":"2026-01-05T09:00:00+00:00","domain":"nike.com","first_seen_at":"2026-01-05T09:00:00+00:00","id":"018e7c2e-33ab-7df1-b1cd-2ac3a8f9112d","last_seen_at":"2026-04-18T09:00:00+00:00","mention_count":42,"name":"Nike","object":"competitor","reason":"Sells running shoes to the same buyers.","report_count":7,"tags":["Retail"],"updated_at":"2026-04-18T09:00:00+00:00","website":"https://www.nike.com"}],"facets":{"categories":{"ai_platform":3,"direct_competitor":12,"indirect_competitor":5,"other":2,"publisher":4},"tags":[{"count":1,"tag":"Retail"}]},"has_more":false,"limit":50,"object":"list","offset":0,"total":1}},"CompetitorMerge":{"properties":{"winner_id":{"type":"string","title":"Winner Id","description":"The competitor to keep."},"loser_ids":{"items":{"type":"string"},"type":"array","maxItems":50,"minItems":1,"title":"Loser Ids","description":"Duplicate competitors to fold into the winner. Their mentions are re-attributed to the winner across past reports in the background."}},"additionalProperties":false,"type":"object","required":["winner_id","loser_ids"],"title":"CompetitorMerge","description":"Merge duplicate entities into one canonical competitor."},"CompetitorMergeResult":{"properties":{"object":{"type":"string","const":"competitor_merge","title":"Object","description":"Always `competitor_merge`.","default":"competitor_merge"},"winner_id":{"type":"string","title":"Winner Id","description":"The competitor the duplicates were merged into."},"merged_count":{"type":"integer","minimum":0.0,"title":"Merged Count","description":"How many duplicate entities were merged into the winner."}},"additionalProperties":false,"type":"object","required":["winner_id","merged_count"],"title":"CompetitorMergeResult","description":"Acknowledgement that a merge was accepted, with report rows updated in the background."},"CompetitorRace":{"properties":{"runs":{"additionalProperties":{"type":"integer"},"type":"object","title":"Runs","description":"Answers each run gave, by run key."},"brand":{"additionalProperties":{"type":"integer"},"type":"object","title":"Brand","description":"Answers naming the brand, by run key."},"competitors":{"items":{"$ref":"#/components/schemas/CompetitorRaceRow"},"type":"array","title":"Competitors","description":"The competitors named most, most first."}},"additionalProperties":false,"type":"object","required":["runs","brand","competitors"],"title":"CompetitorRace","description":"The competitors named most over the runs: per run, its answers, the ones naming the brand and the leaders'."},"CompetitorRaceRow":{"properties":{"name":{"type":"string","title":"Name"},"mentions":{"additionalProperties":{"type":"integer"},"type":"object","title":"Mentions","description":"Answers naming it, by run key."}},"additionalProperties":false,"type":"object","required":["name","mentions"],"title":"CompetitorRaceRow","description":"A competitor and the answers naming it in each run."},"CompetitorShare":{"properties":{"object":{"type":"string","const":"competitor_share","title":"Object","description":"Always `competitor_share`.","default":"competitor_share"},"key":{"type":"string","title":"Key","description":"The entity's key on the Competitors page (its folded name); an empty string on the brand row."},"name":{"type":"string","title":"Name","description":"The competitor's directory name, or the brand's own name on the brand row."},"category":{"type":"string","enum":["direct_competitor","indirect_competitor","ai_platform","publisher","other","my_brand"],"title":"Category","description":"`my_brand` on the brand row, else the relation it is most often named with among those `category` asked for (`direct_competitor` and `indirect_competitor` by default)."},"website":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Website","description":"The entity's website when known."},"is_brand":{"type":"boolean","title":"Is Brand","description":"True on the brand's own row."},"mentions":{"type":"integer","minimum":0.0,"title":"Mentions","description":"AI answers under the filters that name it (an answer naming it twice counts once)."},"share":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Share","description":"Its mentions as a percent of the mentions of the brand and every entity of the relations asked for (0-100)."},"change":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Change","description":"Share in the newer half of the runs under the filters minus share in the older half, in percentage points; null with fewer than two runs."},"platforms":{"items":{"type":"string"},"type":"array","title":"Platforms","description":"Engines that named it, most mentions first (an open set, e.g. `chatgpt`, `gemini`)."},"platform_share":{"additionalProperties":{"type":"number"},"type":"object","title":"Platform Share","description":"Per engine, its mentions as a percent of that engine's mentions of the brand and the entities (0-100)."},"is_new":{"type":"boolean","title":"Is New","description":"True when it was first named in the newer half of the runs; false on the brand row."},"answers_without_brand":{"type":"integer","minimum":0.0,"title":"Answers Without Brand","description":"Answers under the filters that named it and did not name the brand; 0 on the brand row."}},"additionalProperties":false,"type":"object","required":["key","name","category","is_brand","mentions","platforms","platform_share","is_new","answers_without_brand"],"title":"CompetitorShare","description":"One entity's share of voice under the filters, as the Competitors page counts it.","example":{"answers_without_brand":41,"category":"direct_competitor","change":2.5,"is_brand":false,"is_new":false,"key":"asics","mentions":118,"name":"ASICS","object":"competitor_share","platform_share":{"chatgpt":34.0,"gemini":30.2,"perplexity":29.8},"platforms":["chatgpt","gemini","perplexity"],"share":31.4,"website":"https://www.asics.com"}},"CompetitorSummary":{"properties":{"object":{"type":"string","const":"competitor_summary","title":"Object","description":"Always `competitor_summary`.","default":"competitor_summary"},"date_from":{"type":"string","format":"date-time","title":"Date From","description":"Start of the period, inclusive."},"date_to":{"type":"string","format":"date-time","title":"Date To","description":"End of the period, exclusive."},"answers":{"type":"integer","minimum":0.0,"title":"Answers","description":"AI answers under the filters."},"data":{"items":{"$ref":"#/components/schemas/CompetitorShare"},"type":"array","title":"Data","description":"This page of the brand (first) and its competitors, most mentioned first."},"has_more":{"type":"boolean","title":"Has More","description":"True when more rows exist past this page."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Rows under the filters across all pages, the brand's included."},"limit":{"type":"integer","minimum":1.0,"title":"Limit","description":"Page size that was applied."},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Rows skipped before this page."}},"additionalProperties":false,"type":"object","required":["date_from","date_to","answers","data","has_more","total","limit","offset"],"title":"CompetitorSummary","description":"Share of voice of the brand and its competitors under the filters, the numbers the Competitors page shows.","example":{"answers":412,"data":[{"answers_without_brand":41,"category":"direct_competitor","change":2.5,"is_brand":false,"is_new":false,"key":"asics","mentions":118,"name":"ASICS","object":"competitor_share","platform_share":{"chatgpt":34.0,"gemini":30.2,"perplexity":29.8},"platforms":["chatgpt","gemini","perplexity"],"share":31.4,"website":"https://www.asics.com"}],"date_from":"2026-08-21T00:00:00+00:00","date_to":"2026-09-20T00:00:00+00:00","has_more":false,"limit":100,"object":"competitor_summary","offset":0,"total":1}},"CompetitorTagCount":{"properties":{"tag":{"type":"string","title":"Tag","description":"The label, as the team wrote it; a valid `tag` filter."},"count":{"type":"integer","minimum":0.0,"title":"Count","description":"Entities carrying it under the `category` and `search` filters."}},"additionalProperties":false,"type":"object","required":["tag","count"],"title":"CompetitorTagCount","description":"One tag and how many entities carry it."},"CompetitorUpdate":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":200,"minLength":1},{"type":"null"}],"title":"Name","description":"New canonical display name."},"category":{"anyOf":[{"type":"string","enum":["direct_competitor","indirect_competitor","ai_platform","publisher","other","my_brand"]},{"type":"null"}],"title":"Category","description":"Reclassify the entity. One of `direct_competitor`, `indirect_competitor`, `ai_platform`, `publisher`, `other`, `my_brand`. A category change also updates how past reports count it. `my_brand` means the entity is the brand itself: its name and aliases become brand aliases, past reports count its mentions as the brand (visibility and rank are recalculated in the background) and it leaves the competitor directory, so later requests for this id answer `not_found`. Any `name` or `website` sent with it is ignored."},"website":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Website","description":"Website URL for the entity. Send an empty string to clear it."},"tags":{"anyOf":[{"items":{"type":"string","maxLength":40,"minLength":1},"type":"array","maxItems":10},{"type":"null"}],"title":"Tags","description":"Replace the entity's labels (up to 10, 40 characters each). Send `[]` to clear them."}},"additionalProperties":false,"type":"object","title":"CompetitorUpdate","description":"Curate a competitor entity, changing only the fields you send."},"Contact":{"properties":{"object":{"type":"string","const":"contact","title":"Object","default":"contact"},"id":{"type":"string","title":"Id","description":"Contact id."},"brand_id":{"type":"string","title":"Brand Id","description":"Owning brand id."},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email","description":"Email address."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Name."},"company":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company","description":"Company or publication."},"website":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Website","description":"Website."},"linkedin_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Linkedin Url","description":"LinkedIn profile URL."},"twitter_handle":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Twitter Handle","description":"X handle, without the `@`."},"email_verified":{"type":"boolean","title":"Email Verified","description":"Whether the email was verified as deliverable."},"status":{"type":"string","enum":["active","unsubscribed","bounced"],"title":"Status","description":"`active`, `unsubscribed` or `bounced`; only `active` contacts are emailed."},"tags":{"items":{"type":"string"},"type":"array","title":"Tags","description":"Free-form labels; a dynamic list can follow them."},"best_tier":{"anyOf":[{"type":"integer","maximum":6.0,"minimum":1.0},{"type":"null"}],"title":"Best Tier","description":"Best tier across the pages the contact was found on: 1 is the page's author or a named editor, 6 a generic inbox. `null` for a contact added by hand and not found on any page."},"citation_count":{"type":"integer","minimum":0.0,"title":"Citation Count","description":"Cited pages the contact was found on."},"last_contacted_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Last Contacted At","description":"When an email last went to the contact."},"engagement":{"anyOf":[{"$ref":"#/components/schemas/ContactEngagement"},{"type":"null"}],"description":"Email results with the contact; `null` unless the brand owner is on Pro."},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Created At","description":"When the contact was added."},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Updated At","description":"Last change."}},"additionalProperties":false,"type":"object","required":["id","brand_id","email_verified","status","citation_count"],"title":"Contact","description":"A person the brand can pitch: found on a cited page or added by hand.","example":{"best_tier":1,"brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","citation_count":3,"company":"Runner's World","created_at":"2026-09-20T10:00:00+00:00","email":"alex.rivera@e2e.test","email_verified":true,"engagement":{"emails_opened":1,"emails_replied":1,"emails_sent":2,"open_rate":50.0,"reply_rate":50.0},"id":"7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d","name":"Alex Rivera","object":"contact","status":"active","tags":["running","tier-1"],"updated_at":"2026-09-28T10:00:00+00:00","website":"https://www.runnersworld.com"}},"ContactActivity":{"properties":{"type":{"type":"string","enum":["sent","opened","replied"],"title":"Type","description":"What happened."},"email_id":{"type":"string","title":"Email Id","description":"The email, as `GET /v1/brands/{brand_id}/emails` lists it."},"subject":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subject","description":"The email's subject."},"timestamp":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Timestamp","description":"When it happened."}},"additionalProperties":false,"type":"object","required":["type","email_id"],"title":"ContactActivity","description":"One thing that happened with an email to the contact."},"ContactCreate":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Name","description":"Name."},"company":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Company","description":"Company or publication."},"website":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Website","description":"Website; `https://` is added when missing."},"linkedin_url":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Linkedin Url","description":"A linkedin.com profile URL."},"twitter_handle":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"title":"Twitter Handle","description":"An X handle or profile URL."},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":50},{"type":"null"}],"title":"Tags","description":"Free-form labels; a dynamic list can follow them. Replaces the contact's tags."},"email":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Email","description":"Email address. A contact needs at least an email, a name, a LinkedIn URL or an X handle."}},"additionalProperties":false,"type":"object","title":"ContactCreate","description":"A contact added by hand.","example":{"company":"Runner's World","email":"alex.rivera@e2e.test","name":"Alex Rivera"}},"ContactDetail":{"properties":{"object":{"type":"string","const":"contact","title":"Object","default":"contact"},"id":{"type":"string","title":"Id","description":"Contact id."},"brand_id":{"type":"string","title":"Brand Id","description":"Owning brand id."},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email","description":"Email address."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Name."},"company":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company","description":"Company or publication."},"website":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Website","description":"Website."},"linkedin_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Linkedin Url","description":"LinkedIn profile URL."},"twitter_handle":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Twitter Handle","description":"X handle, without the `@`."},"email_verified":{"type":"boolean","title":"Email Verified","description":"Whether the email was verified as deliverable."},"status":{"type":"string","enum":["active","unsubscribed","bounced"],"title":"Status","description":"`active`, `unsubscribed` or `bounced`; only `active` contacts are emailed."},"tags":{"items":{"type":"string"},"type":"array","title":"Tags","description":"Free-form labels; a dynamic list can follow them."},"best_tier":{"anyOf":[{"type":"integer","maximum":6.0,"minimum":1.0},{"type":"null"}],"title":"Best Tier","description":"Best tier across the pages the contact was found on: 1 is the page's author or a named editor, 6 a generic inbox. `null` for a contact added by hand and not found on any page."},"citation_count":{"type":"integer","minimum":0.0,"title":"Citation Count","description":"Cited pages the contact was found on."},"last_contacted_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Last Contacted At","description":"When an email last went to the contact."},"engagement":{"anyOf":[{"$ref":"#/components/schemas/ContactEngagement"},{"type":"null"}],"description":"Email results with the contact; `null` unless the brand owner is on Pro."},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Created At","description":"When the contact was added."},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Updated At","description":"Last change."},"lists":{"items":{"$ref":"#/components/schemas/ContactListRef"},"type":"array","title":"Lists","description":"Static lists the contact is on."},"activity":{"items":{"$ref":"#/components/schemas/ContactActivity"},"type":"array","title":"Activity","description":"The last 50 sends, opens and replies, newest first."}},"additionalProperties":false,"type":"object","required":["id","brand_id","email_verified","status","citation_count"],"title":"ContactDetail","description":"A contact with the lists it is on and its recent email activity.","example":{"activity":[],"best_tier":1,"brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","citation_count":3,"company":"Runner's World","created_at":"2026-09-20T10:00:00+00:00","email":"alex.rivera@e2e.test","email_verified":true,"engagement":{"emails_opened":1,"emails_replied":1,"emails_sent":2,"open_rate":50.0,"reply_rate":50.0},"id":"7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d","lists":[{"id":"9b8a7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d","name":"Running editors"}],"name":"Alex Rivera","object":"contact","status":"active","tags":["running","tier-1"],"updated_at":"2026-09-28T10:00:00+00:00","website":"https://www.runnersworld.com"}},"ContactEngagement":{"properties":{"emails_sent":{"type":"integer","minimum":0.0,"title":"Emails Sent","description":"Emails sent to the contact."},"emails_opened":{"type":"integer","minimum":0.0,"title":"Emails Opened","description":"Of those, opened."},"emails_replied":{"type":"integer","minimum":0.0,"title":"Emails Replied","description":"Of those, replied to."},"open_rate":{"type":"number","title":"Open Rate","description":"Opened over sent, in percent."},"reply_rate":{"type":"number","title":"Reply Rate","description":"Replied over sent, in percent."}},"additionalProperties":false,"type":"object","required":["emails_sent","emails_opened","emails_replied","open_rate","reply_rate"],"title":"ContactEngagement","description":"What the brand's outreach emails to the contact did."},"ContactFilterPreview":{"properties":{"object":{"type":"string","const":"contact_filter_preview","title":"Object","default":"contact_filter_preview"},"count":{"type":"integer","minimum":0.0,"title":"Count","description":"Contacts the filter matches now."},"sample":{"items":{"$ref":"#/components/schemas/Contact"},"type":"array","title":"Sample","description":"A sample of them."}},"additionalProperties":false,"type":"object","required":["count"],"title":"ContactFilterPreview","description":"How many contacts a filter matches now, with a sample."},"ContactFilterPreviewCreate":{"properties":{"segment_filters":{"$ref":"#/components/schemas/SegmentFilter","description":"The filter."},"sample_limit":{"type":"integer","maximum":20.0,"minimum":1.0,"title":"Sample Limit","description":"Contacts to return as a sample (1 to 20).","default":5}},"additionalProperties":false,"type":"object","required":["segment_filters"],"title":"ContactFilterPreviewCreate","description":"A dynamic list's filter to try before saving it.","example":{"segment_filters":{"conditions":[{"field":"tier","operator":"lte","value":2},{"field":"email_verified","operator":"equals","value":true}],"operator":"AND"}}},"ContactList":{"properties":{"object":{"type":"string","const":"contact_list","title":"Object","default":"contact_list"},"id":{"type":"string","title":"Id","description":"Contact list id."},"brand_id":{"type":"string","title":"Brand Id","description":"Owning brand id."},"name":{"type":"string","title":"Name","description":"Name."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Description."},"is_dynamic":{"type":"boolean","title":"Is Dynamic","description":"A dynamic list holds whatever contacts match `segment_filters` now."},"segment_filters":{"$ref":"#/components/schemas/SegmentFilter","description":"A dynamic list's filter; empty for a static list."},"contact_count":{"type":"integer","minimum":0.0,"title":"Contact Count","description":"Contacts on the list now."},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Created At","description":"When the list was created."},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Updated At","description":"Last change."}},"additionalProperties":false,"type":"object","required":["id","brand_id","name","is_dynamic","segment_filters","contact_count"],"title":"ContactList","description":"A list a campaign sends to: static (contacts added one by one) or dynamic (it follows a filter).","example":{"brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","contact_count":42,"created_at":"2026-09-20T10:00:00+00:00","description":"Tier 1 and 2 with a verified email","id":"9b8a7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d","is_dynamic":true,"name":"Running editors","object":"contact_list","segment_filters":{"conditions":[{"field":"tier","operator":"lte","value":2},{"field":"email_verified","operator":"equals","value":true}],"operator":"AND"},"updated_at":"2026-09-20T10:00:00+00:00"}},"ContactListCreate":{"properties":{"name":{"type":"string","maxLength":200,"minLength":1,"title":"Name","description":"Name."},"description":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Description","description":"Description."},"is_dynamic":{"type":"boolean","title":"Is Dynamic","description":"`true` for a list that follows `segment_filters`.","default":false},"segment_filters":{"anyOf":[{"$ref":"#/components/schemas/SegmentFilter"},{"type":"null"}],"description":"Required with at least one condition for a dynamic list."}},"additionalProperties":false,"type":"object","required":["name"],"title":"ContactListCreate","description":"A new contact list.","example":{"is_dynamic":true,"name":"Running editors","segment_filters":{"conditions":[{"field":"tier","operator":"lte","value":2},{"field":"email_verified","operator":"equals","value":true}],"operator":"AND"}}},"ContactListList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/ContactList"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Opaque continuation token. Pass back as `?cursor=` to fetch the next page. `null` when `has_more` is false."}},"additionalProperties":false,"type":"object","required":["data","has_more"],"title":"ContactListList","description":"A page of contact lists, newest first.","example":{"data":[{"brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","contact_count":42,"created_at":"2026-09-20T10:00:00+00:00","description":"Tier 1 and 2 with a verified email","id":"9b8a7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d","is_dynamic":true,"name":"Running editors","object":"contact_list","segment_filters":{"conditions":[{"field":"tier","operator":"lte","value":2},{"field":"email_verified","operator":"equals","value":true}],"operator":"AND"},"updated_at":"2026-09-20T10:00:00+00:00"}],"has_more":false,"object":"list"}},"ContactListMember":{"properties":{"object":{"type":"string","const":"contact","title":"Object","default":"contact"},"id":{"type":"string","title":"Id","description":"Contact id."},"brand_id":{"type":"string","title":"Brand Id","description":"Owning brand id."},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email","description":"Email address."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Name."},"company":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company","description":"Company or publication."},"website":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Website","description":"Website."},"linkedin_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Linkedin Url","description":"LinkedIn profile URL."},"twitter_handle":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Twitter Handle","description":"X handle, without the `@`."},"email_verified":{"type":"boolean","title":"Email Verified","description":"Whether the email was verified as deliverable."},"status":{"type":"string","enum":["active","unsubscribed","bounced"],"title":"Status","description":"`active`, `unsubscribed` or `bounced`; only `active` contacts are emailed."},"tags":{"items":{"type":"string"},"type":"array","title":"Tags","description":"Free-form labels; a dynamic list can follow them."},"best_tier":{"anyOf":[{"type":"integer","maximum":6.0,"minimum":1.0},{"type":"null"}],"title":"Best Tier","description":"Best tier across the pages the contact was found on: 1 is the page's author or a named editor, 6 a generic inbox. `null` for a contact added by hand and not found on any page."},"citation_count":{"type":"integer","minimum":0.0,"title":"Citation Count","description":"Cited pages the contact was found on."},"last_contacted_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Last Contacted At","description":"When an email last went to the contact."},"engagement":{"anyOf":[{"$ref":"#/components/schemas/ContactEngagement"},{"type":"null"}],"description":"Email results with the contact; `null` unless the brand owner is on Pro."},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Created At","description":"When the contact was added."},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Updated At","description":"Last change."},"citation_contact_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Citation Contact Id","description":"The contact's link to the page it was added with, if any."},"page_context":{"anyOf":[{"$ref":"#/components/schemas/ContactListPageContext"},{"type":"null"}],"description":"That page, as the list's emails name it."}},"additionalProperties":false,"type":"object","required":["id","brand_id","email_verified","status","citation_count"],"title":"ContactListMember","description":"A contact on a list, with the cited page it was added with.","example":{"best_tier":1,"brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","citation_count":3,"company":"Runner's World","created_at":"2026-09-20T10:00:00+00:00","email":"alex.rivera@e2e.test","email_verified":true,"engagement":{"emails_opened":1,"emails_replied":1,"emails_sent":2,"open_rate":50.0,"reply_rate":50.0},"id":"7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d","name":"Alex Rivera","object":"contact","status":"active","tags":["running","tier-1"],"updated_at":"2026-09-28T10:00:00+00:00","website":"https://www.runnersworld.com"}},"ContactListMemberList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/ContactListMember"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"True when more items exist past this page. Fetch them with a larger `offset`."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of items matching the query, across all pages."},"limit":{"type":"integer","minimum":1.0,"title":"Limit","description":"Page size that was applied."},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of items skipped before this page."}},"additionalProperties":false,"type":"object","required":["data","has_more","total","limit","offset"],"title":"ContactListMemberList","description":"A page of a list's contacts."},"ContactListMembersAdd":{"properties":{"contact_ids":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":500,"minItems":1},{"type":"null"}],"title":"Contact Ids","description":"Contact ids."},"contacts_with_pages":{"anyOf":[{"items":{"$ref":"#/components/schemas/ContactWithPage"},"type":"array","maxItems":500,"minItems":1},{"type":"null"}],"title":"Contacts With Pages","description":"Contacts with their page, so the emails can name it. Send this or `contact_ids`."}},"additionalProperties":false,"type":"object","title":"ContactListMembersAdd","description":"Contacts to add to a static list: plain ids, or ids with the page each was found on.","example":{"contact_ids":["7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d"]}},"ContactListMembersAdded":{"properties":{"object":{"type":"string","const":"contact_list_members_added","title":"Object","default":"contact_list_members_added"},"added":{"type":"integer","minimum":0.0,"title":"Added","description":"Contacts added."},"skipped":{"type":"integer","minimum":0.0,"title":"Skipped","description":"Contacts that were already on the list."}},"additionalProperties":false,"type":"object","required":["added","skipped"],"title":"ContactListMembersAdded","description":"How many contacts joined the list.","example":{"added":1,"object":"contact_list_members_added","skipped":0}},"ContactListPageContext":{"properties":{"page_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Page Url","description":"The page URL."},"page_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Page Title","description":"The page title."},"role":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Role","description":"The contact's role on the page."}},"additionalProperties":false,"type":"object","title":"ContactListPageContext","description":"The cited page a list member was added with, which fills `{{page_url}}`, `{{page_title}}` and `{{role}}`."},"ContactListRef":{"properties":{"id":{"type":"string","title":"Id","description":"Contact list id."},"name":{"type":"string","title":"Name","description":"List name."}},"additionalProperties":false,"type":"object","required":["id","name"],"title":"ContactListRef","description":"A contact list a contact is on."},"ContactListUpdate":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":200,"minLength":1},{"type":"null"}],"title":"Name","description":"Name."},"description":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Description","description":"Description."},"segment_filters":{"anyOf":[{"$ref":"#/components/schemas/SegmentFilter"},{"type":"null"}],"description":"A dynamic list's new filter."}},"additionalProperties":false,"type":"object","title":"ContactListUpdate","description":"Changes to a contact list.","example":{"name":"Running editors, tier 1"}},"ContactPage":{"properties":{"object":{"type":"string","const":"contact_page","title":"Object","default":"contact_page"},"citation_contact_id":{"type":"string","title":"Citation Contact Id","description":"The contact's link to this page; pass it to a static list to keep the page in the emails."},"citation_id":{"type":"string","title":"Citation Id","description":"The cited page's id."},"url":{"type":"string","title":"Url","description":"The page URL."},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain","description":"The page's domain."},"page_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Page Title","description":"The page title."},"role":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Role","description":"The contact's role on the page."},"department":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Department","description":"Department."},"seniority":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Seniority","description":"Seniority."},"tier":{"anyOf":[{"type":"integer","maximum":6.0,"minimum":1.0},{"type":"null"}],"title":"Tier","description":"Tier on this page: 1 is the author or a named editor."},"is_page_author":{"type":"boolean","title":"Is Page Author","description":"Whether the contact wrote the page."},"is_primary":{"type":"boolean","title":"Is Primary","description":"Whether the contact is the page's primary contact."},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Created At","description":"When the contact was found on the page."}},"additionalProperties":false,"type":"object","required":["citation_contact_id","citation_id","url","is_page_author","is_primary"],"title":"ContactPage","description":"A cited page a contact was found on, with their role there."},"ContactPages":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/ContactPage"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"True when more items exist past this page. Fetch them with a larger `offset`."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of items matching the query, across all pages."},"limit":{"type":"integer","minimum":1.0,"title":"Limit","description":"Page size that was applied."},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of items skipped before this page."}},"additionalProperties":false,"type":"object","required":["data","has_more","total","limit","offset"],"title":"ContactPages","description":"A page of the cited pages a contact was found on, best tier first."},"ContactTagging":{"properties":{"contact_ids":{"items":{"type":"string"},"type":"array","maxItems":100,"minItems":1,"title":"Contact Ids","description":"Contacts to tag (1 to 100)."},"tags":{"items":{"type":"string"},"type":"array","maxItems":20,"minItems":1,"title":"Tags","description":"Tags (1 to 20, up to 100 characters each)."},"action":{"type":"string","enum":["add","remove"],"title":"Action","description":"`add` (default) or `remove`.","default":"add"}},"additionalProperties":false,"type":"object","required":["contact_ids","tags"],"title":"ContactTagging","description":"Tags to add to or remove from several contacts at once.","example":{"action":"add","contact_ids":["7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d"],"tags":["running"]}},"ContactTaggingResult":{"properties":{"object":{"type":"string","const":"contact_tagging","title":"Object","default":"contact_tagging"},"updated":{"type":"integer","minimum":0.0,"title":"Updated","description":"Contacts whose tags changed."}},"additionalProperties":false,"type":"object","required":["updated"],"title":"ContactTaggingResult","description":"How many contacts changed.","example":{"object":"contact_tagging","updated":1}},"ContactUpdate":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Name","description":"Name."},"company":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Company","description":"Company or publication."},"website":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Website","description":"Website; `https://` is added when missing."},"linkedin_url":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Linkedin Url","description":"A linkedin.com profile URL."},"twitter_handle":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"title":"Twitter Handle","description":"An X handle or profile URL."},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":50},{"type":"null"}],"title":"Tags","description":"Free-form labels; a dynamic list can follow them. Replaces the contact's tags."}},"additionalProperties":false,"type":"object","title":"ContactUpdate","description":"Profile changes; the email cannot change.","example":{"tags":["running","tier-1"]}},"ContactWithPage":{"properties":{"contact_id":{"type":"string","title":"Contact Id","description":"Contact id."},"citation_contact_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Citation Contact Id","description":"Its link to a cited page, from `GET /v1/brands/{brand_id}/contacts/{contact_id}/citations`."}},"additionalProperties":false,"type":"object","required":["contact_id"],"title":"ContactWithPage","description":"A contact to add, with the cited page it was found on."},"Contacts":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/Contact"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"True when more items exist past this page. Fetch them with a larger `offset`."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of items matching the query, across all pages."},"limit":{"type":"integer","minimum":1.0,"title":"Limit","description":"Page size that was applied."},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of items skipped before this page."}},"additionalProperties":false,"type":"object","required":["data","has_more","total","limit","offset"],"title":"Contacts","description":"A page of contacts.","example":{"data":[{"best_tier":1,"brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","citation_count":3,"company":"Runner's World","created_at":"2026-09-20T10:00:00+00:00","email":"alex.rivera@e2e.test","email_verified":true,"engagement":{"emails_opened":1,"emails_replied":1,"emails_sent":2,"open_rate":50.0,"reply_rate":50.0},"id":"7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d","name":"Alex Rivera","object":"contact","status":"active","tags":["running","tier-1"],"updated_at":"2026-09-28T10:00:00+00:00","website":"https://www.runnersworld.com"}],"has_more":false,"limit":20,"object":"list","offset":0,"total":1}},"ContentAsset":{"properties":{"object":{"type":"string","const":"content_asset","title":"Object","description":"Always `content_asset`.","default":"content_asset"},"id":{"type":"string","title":"Id","description":"Asset id (UUID)."},"asset_type":{"type":"string","enum":["article","image","meta"],"title":"Asset Type","description":"Asset kind. One of `article`, `image`, `meta`."},"summary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Summary","description":"Short summary or meta description for the asset."},"storage_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Storage Path","description":"Public URL of a stored image asset, when applicable."},"image_prompt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Prompt","description":"Prompt used to generate an image asset, when applicable."},"html_content":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Html Content","description":"Rendered article HTML for an `article` asset."},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata","description":"Asset metadata such as title, slug, SEO fields, and image placement."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the asset was created."},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Updated At","description":"When the asset last changed. Send it as `expected_updated_at` when editing the article."}},"additionalProperties":false,"type":"object","required":["id","asset_type","created_at"],"title":"ContentAsset","description":"A generated asset attached to a content brief (article HTML, image, or meta block)."},"ContentAssetMeta":{"properties":{"title":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Title","description":"Also becomes the brief's title."},"seo_title":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}],"title":"Seo Title","description":"The title search results show (SEO plugins, Ghost, Shopify, Webflow, Wix, webhooks), up to 60 characters to show whole; empty publishes the title."},"slug":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}],"title":"Slug","description":"URL slug the article publishes under."},"meta_description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Meta Description"},"focus_keyword":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Focus Keyword"},"featured_image":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Featured Image","description":"URL of the image that publishes with the article."},"featured_image_alt":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}],"title":"Featured Image Alt"},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":30},{"type":"null"}],"title":"Tags","description":"Post tags. The target keywords are used when this is not set."}},"additionalProperties":false,"type":"object","title":"ContentAssetMeta","description":"The article's own metadata: what publishes as the page's title, slug and description."},"ContentAssetsUpdate":{"properties":{"article_html":{"anyOf":[{"type":"string","maxLength":500000,"minLength":1},{"type":"null"}],"title":"Article Html","description":"The whole article body as HTML. It is sanitised, so scripts and event handlers are dropped. It cannot be empty: to shorten an article, send the shorter article."},"meta":{"anyOf":[{"$ref":"#/components/schemas/ContentAssetMeta"},{"type":"null"}],"description":"Merged over what the article already has."},"expected_updated_at":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}],"title":"Expected Updated At","description":"The article asset's `updated_at` you edited from. When the article changed since (the user saved it in the editor), the edit is refused with 409 `conflict` and `details.updated_at`; read it again and re-apply. Omitted, the edit overwrites."}},"additionalProperties":false,"type":"object","title":"ContentAssetsUpdate","description":"Edit the generated article: its body, its metadata, or both."},"ContentAutopilot":{"properties":{"object":{"type":"string","const":"content_autopilot","title":"Object","description":"Always `content_autopilot`.","default":"content_autopilot"},"configured":{"type":"boolean","title":"Configured","description":"False while the brand never saved an autopilot; the values are then the defaults."},"enabled":{"type":"boolean","title":"Enabled","description":"Whether the autopilot writes and publishes."},"weekdays":{"items":{"type":"integer"},"type":"array","title":"Weekdays","description":"ISO weekdays with a slot, 1 (Monday) to 7 (Sunday)."},"publish_time":{"type":"string","title":"Publish Time","description":"Local time of each slot, `HH:MM`."},"time_zone":{"type":"string","title":"Time Zone","description":"IANA time zone the slots are read in."},"target_type":{"anyOf":[{"type":"string","enum":["hosted_site","cms_connection"]},{"type":"null"}],"title":"Target Type","description":"`cms_connection` or `hosted_site`; null while the autopilot only leaves drafts."},"target_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Id","description":"The connection or hosted site it publishes to."},"policy":{"type":"string","enum":["draft_only","publish_after_review_window","auto_publish"],"title":"Policy","description":"`draft_only` leaves each article for someone to publish, `publish_after_review_window` publishes it `review_window_hours` after it is written unless someone stops it, `auto_publish` publishes at the slot."},"review_window_hours":{"type":"integer","title":"Review Window Hours","description":"Hours an article waits before `publish_after_review_window` publishes it."},"monthly_cap":{"type":"integer","title":"Monthly Cap","description":"Most articles the autopilot writes in a calendar month."},"pinned_topics":{"items":{"type":"string"},"type":"array","title":"Pinned Topics","description":"Topics written first, in this order."},"excluded_topics":{"items":{"type":"string"},"type":"array","title":"Excluded Topics","description":"Topics never written."},"min_quality":{"type":"integer","title":"Min Quality","description":"Lowest quality score an article can have and still be published by the autopilot."},"require_links_valid":{"type":"boolean","title":"Require Links Valid","description":"When true an article whose link check removed a link, raised a warning or could not verify a claim is held for review."},"pause_reason":{"anyOf":[{"type":"string","enum":["credits","no_topics","target_missing","plan","failures","blog_offline"]},{"type":"null"}],"title":"Pause Reason","description":"Why the autopilot paused itself: `credits` (the owner ran out), `no_topics`, `target_missing` (the destination went away), `plan` (lifts on its own within the hour once the owner's plan includes the autopilot again), `blog_offline` (its hosted blog went offline because the owner's account has no plan that includes the blog; lifts on its own once the blog is back) or `failures` (three articles in a row failed to write or to publish). Null while it runs."},"next_run_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Next Run At","description":"The next slot the monthly cap allows: once this month's `monthly_cap` articles are written, the first slot of the next month. Null whenever `enabled` is false or a pause is on."},"last_run_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Last Run At","description":"When the last run started."},"last_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Error","description":"Why the last attempt to work the autopilot failed on our side; cleared by the next run."},"articles_per_month":{"type":"integer","title":"Articles Per Month","description":"Articles the current settings write in a month, after the cap."},"credits_per_article":{"type":"integer","title":"Credits Per Article","description":"Credits one article costs the brand owner."},"credits_per_month":{"type":"integer","title":"Credits Per Month","description":"Credits a month costs at the current settings."},"runs_this_month":{"type":"integer","title":"Runs This Month","description":"Runs whose slot falls in this calendar month (in `time_zone`) that count against `monthly_cap`."},"last_run":{"anyOf":[{"$ref":"#/components/schemas/ContentAutopilotRun"},{"type":"null"}],"description":"The newest run, when there is one."}},"additionalProperties":false,"type":"object","required":["configured","enabled","weekdays","publish_time","time_zone","policy","review_window_hours","monthly_cap","pinned_topics","excluded_topics","min_quality","require_links_valid","articles_per_month","credits_per_article","credits_per_month","runs_this_month"],"title":"ContentAutopilot","description":"A brand's content autopilot: its weekly slots, destination, policy, limits and state."},"ContentAutopilotRun":{"properties":{"object":{"type":"string","const":"content_autopilot_run","title":"Object","description":"Always `content_autopilot_run`.","default":"content_autopilot_run"},"id":{"type":"string","title":"Id","description":"Run id (UUID)."},"slot_at":{"type":"string","title":"Slot At","description":"The slot the run belongs to, ISO 8601 in UTC."},"status":{"type":"string","enum":["generating","scheduled","ready","held","published","failed","skipped"],"title":"Status","description":"`generating` (the article is being written), `scheduled` (waiting for its slot), `ready` (a draft waiting for someone), `held` (kept back by a quality or link check), `published`, `failed` or `skipped` (it stopped before going live: the article was deleted or left review another way, its publish was cancelled or missed its time while the brand owner's plan did not include publishing, or the autopilot was turned off before it was paid for; `reason` says which)."},"topic":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Topic","description":"The topic the run picked."},"brief_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brief Id","description":"The content brief the run wrote, when it got that far."},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"Why the run was held, skipped or failed, as a code."},"detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detail","description":"The reason in words."},"review_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Review Url","description":"The pull request a `scheduled` run's article waits on; it goes live once that is merged."},"written_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Written At","description":"When the article finished writing; the run then reads `scheduled`, `ready` or `held` at once."}},"additionalProperties":false,"type":"object","required":["id","slot_at","status"],"title":"ContentAutopilotRun","description":"One slot's run: what the autopilot did, or is doing, for that slot."},"ContentAutopilotUpdate":{"properties":{"enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Enabled","description":"Turn the autopilot on or off."},"weekdays":{"anyOf":[{"items":{"type":"integer"},"type":"array","maxItems":7,"minItems":1},{"type":"null"}],"title":"Weekdays","description":"ISO weekdays with a slot, 1 (Monday) to 7 (Sunday)."},"publish_time":{"anyOf":[{"type":"string","maxLength":5},{"type":"null"}],"title":"Publish Time","description":"Local time of each slot, `HH:MM`."},"time_zone":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Time Zone","description":"IANA time zone, e.g. `America/New_York`."},"target_type":{"anyOf":[{"type":"string","enum":["hosted_site","cms_connection"]},{"type":"null"}],"title":"Target Type","description":"`cms_connection` with a `target_id` from `GET .../publish-targets` (the default when only `target_id` is sent), or `hosted_site` (the brand's hosted blog; no `target_id` needed)."},"target_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Id","description":"The connection it publishes to; `null` clears the destination."},"policy":{"anyOf":[{"type":"string","enum":["draft_only","publish_after_review_window","auto_publish"]},{"type":"null"}],"title":"Policy","description":"`draft_only` leaves each article for someone to publish, `publish_after_review_window` publishes it `review_window_hours` after it is written unless someone stops it, `auto_publish` publishes at the slot."},"review_window_hours":{"anyOf":[{"type":"integer","maximum":168.0,"minimum":1.0},{"type":"null"}],"title":"Review Window Hours","description":"Hours, 1 to 168, an article waits before `publish_after_review_window` publishes it."},"monthly_cap":{"anyOf":[{"type":"integer","maximum":62.0,"minimum":1.0},{"type":"null"}],"title":"Monthly Cap","description":"Most articles in a calendar month. Left out while `weekdays` change, a cap still at the old weekdays' default follows the new one."},"pinned_topics":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":50},{"type":"null"}],"title":"Pinned Topics","description":"Topics written first, in this order; replaces the list. Up to 50, each up to 200 characters."},"excluded_topics":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":50},{"type":"null"}],"title":"Excluded Topics","description":"Topics never written; replaces the list. Up to 50, each up to 200 characters."},"min_quality":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Min Quality","description":"Lowest quality score, 0 to 100, an article can have and still be published by the autopilot."},"require_links_valid":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Require Links Valid","description":"When true an article whose link check removed a link, raised a warning or could not verify a claim is held for review."},"resume":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Resume","description":"True resumes an autopilot that paused itself, after fixing what paused it. A `plan` pause lifts on its own, and resuming it answers 400."}},"additionalProperties":false,"type":"object","title":"ContentAutopilotUpdate","description":"A partial change to the autopilot; the first change creates it."},"ContentBrief":{"properties":{"object":{"type":"string","const":"content_brief","title":"Object","description":"Always `content_brief`.","default":"content_brief"},"id":{"type":"string","title":"Id","description":"Content brief id (UUID)."},"brand_id":{"type":"string","title":"Brand Id","description":"Owning brand id (UUID)."},"status":{"type":"string","enum":["draft","processing","needs_review","published","failed"],"title":"Status","description":"Brief lifecycle state. One of `draft`, `processing`, `needs_review`, `published`, `failed`."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"Brief title, set on creation or filled in from the article."},"topic":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Topic","description":"Topic or target keyword the content is written around."},"content_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content Type","description":"Content format id (e.g. `blog_post`, `ranked_list`)."},"mode":{"type":"string","enum":["create","optimize"],"title":"Mode","description":"`create` writes a new article; `optimize` improves the page at `source_url` (`content-optimizations`).","default":"create"},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Url","description":"The brand's own page an `optimize` brief improves."},"optimize_level":{"anyOf":[{"type":"string","enum":["conservative","balanced","full"]},{"type":"null"}],"title":"Optimize Level","description":"How far an `optimize` brief goes; null for `create`."},"target_keywords":{"items":{"type":"string"},"type":"array","title":"Target Keywords","description":"Target keywords for the brief."},"content_context":{"additionalProperties":true,"type":"object","title":"Content Context","description":"The format's own fields (the ones a content opportunity pre-fills, e.g. `listTheme` and `listSize` for `ranked_list`), plus `sources`: `{\"urls\": [...], \"only_mine\": false}`, up to 10 pages or PDFs the article reads before writing and cites, each reported in `quality_report.enforcement.sources` as `used`, `not_used` or `source_unreadable` (`only_mine: true` turns web search off and unwraps any other outside link), `sourcePrompts`: ids of the report prompts the article answers, and `length`: `{\"mode\": \"auto\"|\"short\"|\"standard\"|\"long\"}` or `{\"mode\": \"exact\", \"words\": 300-5000}` (omitted: the brand's `default_length`), and `blockedWords`: up to 100 phrases of up to 100 characters this article must not use on top of the brand's `banned_phrases`, and `knowledge`: `{\"mode\": \"auto\"}` (the knowledge base chunks closest to the topic, the default), `{\"mode\": \"pick\", \"ids\": [...]}` (only those knowledge base items) or `{\"mode\": \"off\"}`. This article only: `language` (a language name, over the brand's), `tone` (up to 200 characters, over the brand's), `audience` (who it is written for, up to 200 characters) and `tools` (`{tool: on|off|auto}` over the brand's AI tools, see content preferences). Other keys are ignored; the brand's banned phrases stay in its preferences."},"generated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Generated At","description":"When content was last generated, if ever."},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message","description":"User-facing failure reason when `status` is `failed`."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the brief was created."},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Updated At","description":"When the brief was last updated."},"quality_report":{"anyOf":[{"additionalProperties":true,"type":"object"},{"items":{},"type":"array"},{"type":"null"}],"title":"Quality Report","description":"Rule-based checks run on the finished article: `{score, axes[], checks[], notes[], words, language, link_check}`, where `score` is the percentage of weighted checks that passed. `link_check` is the source check run after writing: `checked` (how many external links were fetched), `removed[]` (links unwrapped because the page is gone: `url`, `reason`, `status`), `warnings[]` (links kept but worth a look, each `{url, reason}`: `moved_to_root` when a deep link now lands on the site's home page, with the `final_url` it landed on, `unverified` when the research never read the page) and `unverified_claims[]` (`{sentence, numbers[], urls[], reason}`, `reason` being `not_on_source` when the cited page does not carry the figures, `source_removed` when every cited link was removed, `source_unreadable` when no cited page could be read). Advisory only; it never blocks publishing."},"review_due_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Review Due At","description":"When the article's fastest-ageing fact (a price, a plan tier) is worth re-checking."},"planned_publish_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Planned Publish At","description":"The day the article sits on in the content calendar until it is published or a publish is queued; null when it has none. Set it with `PATCH /v1/brands/{brand_id}/content-briefs/{brief_id}`."},"publications":{"items":{"$ref":"#/components/schemas/ContentPublication"},"type":"array","title":"Publications","description":"Every place the article was published, with its live URL. Empty until it is published."},"market":{"anyOf":[{"$ref":"#/components/schemas/ContentBriefMarket"},{"type":"null"}],"description":"The market its source prompts were asked in, when they share one (a brief created from a missed prompt or a report gap of that market); null otherwise, and the article writes for the brand's own country."},"outline_json":{"anyOf":[{"additionalProperties":true,"type":"object"},{"items":{},"type":"array"},{"type":"null"}],"title":"Outline Json","description":"Structured article outline produced during generation."},"research_output":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Research Output","description":"Research notes gathered during generation."},"serp_research":{"anyOf":[{"additionalProperties":true,"type":"object"},{"items":{},"type":"array"},{"type":"null"}],"title":"Serp Research","description":"What Google ranked for the target keyword when the article was researched: `pages` (rank, url, domain, title, words, published_at, reachable), `people_also_ask`, `features`, `table_stakes` (subtopics most top pages cover), `differentiators`, `median_words` and `intent` (Google's main intent for the keyword: `informational`, `commercial`, `transactional` or `navigational`, null when unknown). Null when the results page was unavailable."},"generation_settings":{"anyOf":[{"additionalProperties":true,"type":"object"},{"items":{},"type":"array"},{"type":"null"}],"title":"Generation Settings","description":"What the last run wrote with and where each value came from: `language`, `tone`, `length`, `audience`, `banned_phrases`, `knowledge` and `sources` as `{value, origin}`, and `tools` as `{value: {tool: mode}, origin: {tool: origin}}`; `origin` is `article` (this brief's `content_context`), `brand` (the brand's content preferences) or `system`. A regeneration keeps the brand values it records unless asked for today's. Null before the first run."},"opportunity_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Opportunity Id","description":"The content opportunity this article answers, when it was created from one."},"assets":{"items":{"$ref":"#/components/schemas/ContentAsset"},"type":"array","title":"Assets","description":"Generated assets (article HTML, images, meta)."}},"additionalProperties":false,"type":"object","required":["id","brand_id","status","created_at"],"title":"ContentBrief","description":"A complete content brief, including its generated assets, outline, and research output."},"ContentBriefCreate":{"properties":{"title":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Title","description":"Optional title; the generator fills one in when omitted."},"topic":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Topic","description":"Topic or target keyword to write about. Provide this or at least one `target_keywords` entry."},"target_keywords":{"items":{"type":"string"},"type":"array","maxItems":20,"title":"Target Keywords","description":"Target keywords to write around (each up to 200 chars)."},"content_type":{"anyOf":[{"type":"string","enum":["blog_post","comparative_article","ranked_list","geo_spotlight","case_study","product_deep_dive","faq_article","citation_faq","statistics_roundup","glossary","how_to","landing_page","product_page"]},{"type":"null"}],"title":"Content Type","description":"Content format to generate; inferred from the topic when omitted."},"source_prompt_ids":{"items":{"type":"string"},"type":"array","maxItems":50,"title":"Source Prompt Ids","description":"Report prompts this article is written to answer. They are snapshotted now, so the citation uplift can later say which of them came back."},"content_context":{"additionalProperties":true,"type":"object","title":"Content Context","description":"The format's own fields (the ones a content opportunity pre-fills, e.g. `listTheme` and `listSize` for `ranked_list`), plus `sources` (see the brief's `content_context`), and `length`, `knowledge`, `language`, `tone`, `audience` and `tools` (see the brief's `content_context`). Those keys are checked: an unknown `language`, a `tone` or `audience` over 200 characters, a tool or mode outside the lists, or a source that is not an http(s) address answers 422. Other keys are ignored."},"opportunity_id":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}],"title":"Opportunity Id","description":"The `id` of the content opportunity this article answers."},"planned_publish_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Planned Publish At","description":"When it should go live. It prefills the CMS schedule; nothing fires from it."}},"additionalProperties":false,"type":"object","title":"ContentBriefCreate","description":"Create a content brief and generate its content inline (costs credits, runs the AI pipeline)."},"ContentBriefDispatched":{"properties":{"object":{"type":"string","const":"content_brief.generation.dispatched","title":"Object","description":"Always `content_brief.generation.dispatched`.","default":"content_brief.generation.dispatched"},"brand_id":{"type":"string","title":"Brand Id","description":"Brand the article is being written for."},"brief_id":{"type":"string","title":"Brief Id","description":"The brief that was created. It is in `processing` until generation finishes."},"job_id":{"type":"string","title":"Job Id","description":"Poll `GET /v1/jobs/{job_id}` for progress. Equal to `brief_id`, since one article is one job."}},"additionalProperties":false,"type":"object","required":["brand_id","brief_id","job_id"],"title":"ContentBriefDispatched","description":"Response body for ``POST /v1/brands/{brand_id}/content-briefs/generations``.","example":{"brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","brief_id":"8c2d4f1e-5a3b-4c7d-9e1f-2a3b4c5d6e7f","job_id":"8c2d4f1e-5a3b-4c7d-9e1f-2a3b4c5d6e7f","object":"content_brief.generation.dispatched"}},"ContentBriefList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/ContentBriefSummary"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Opaque continuation token. Pass back as `?cursor=` to fetch the next page. `null` when `has_more` is false."}},"additionalProperties":false,"type":"object","required":["data","has_more"],"title":"ContentBriefList","description":"A page of content briefs."},"ContentBriefManualCreate":{"properties":{"title":{"type":"string","maxLength":500,"minLength":1,"title":"Title","description":"Article title."},"article_html":{"type":"string","maxLength":500000,"minLength":1,"title":"Article Html","description":"The article body as HTML. Standard tags only: it is rendered in the editor and the review view."},"meta_description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Meta Description","description":"Meta description used when publishing."},"target_keywords":{"items":{"type":"string"},"type":"array","maxItems":20,"title":"Target Keywords","description":"Keywords to carry as tags when publishing."},"content_type":{"anyOf":[{"type":"string","enum":["blog_post","comparative_article","ranked_list","geo_spotlight","case_study","product_deep_dive","faq_article","citation_faq","statistics_roundup","glossary","how_to","landing_page","product_page"]},{"type":"null"}],"title":"Content Type","description":"Content format. Defaults to the brand's usual format when omitted."}},"additionalProperties":false,"type":"object","required":["title","article_html"],"title":"ContentBriefManualCreate","description":"An article written outside RankPrompt, handed over as-is."},"ContentBriefMarket":{"properties":{"object":{"type":"string","const":"content_brief_market","title":"Object","description":"Always `content_brief_market`.","default":"content_brief_market"},"place_key":{"type":"string","title":"Place Key","description":"`country|city` lowercased (`country|city|region` for a town keyed apart from its namesake), the `place` filter of the calendar and reads."},"country":{"type":"string","title":"Country","description":"The market's country: Google is read there and the article writes for it."},"city":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"City","description":"The market's city as Google spells it (the city of its place_key); null for a country."},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language","description":"The language that market asks in: the article's unless its context sets one."}},"additionalProperties":false,"type":"object","required":["place_key","country"],"title":"ContentBriefMarket","description":"The market a brief's source prompts were asked in: what its research and writing target."},"ContentBriefPublish":{"properties":{"target_type":{"type":"string","enum":["cms_connection","hosted_site","external"],"title":"Target Type","description":"Where to publish:\n- `cms_connection`: push the article to a connected destination (WordPress, Ghost, Shopify, Webflow, Wix, a GitHub repository or a webhook). Set `target_id` to the connection id from `GET /v1/brands/{brand_id}/cms-connections`.\n- `hosted_site`: publish to the brand's RankPrompt-hosted blog, which is resolved from the brand. The hosted site must already be active; setting one up needs interactive DNS in the app.\n- `external`: publish nothing, just mark the brief published and record `external_url`, for when you pushed the article somewhere else yourself.","default":"external"},"target_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Id","description":"The CMS connection id, required for `cms_connection`. Leave it out for `hosted_site`, which is resolved from the brand, and for `external`."},"publish_status":{"type":"string","enum":["draft","publish"],"title":"Publish Status","description":"Whether the CMS post goes live (`publish`) or is created as a draft for someone to review in the CMS (`draft`). Ignored for `external`.\n\nLeft out, the post goes live even when the brand's owner has every send to that site start as a draft: read the target's `default_status` (`GET .../publish-targets` or `GET .../cms-connections`) and send `draft` when it says `draft`, unless the person asked for it live.","default":"publish"},"scheduled_for":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Scheduled For","description":"Publish at this time instead of now, as an ISO-8601 datetime in the future. The post waits on the site as a draft (the hosted blog keeps it in RankPrompt) until our queue makes it live at that time, retrying a site that does not answer; the brief stays in `needs_review` until then. Not accepted with `publish_status: draft`.\n\nScheduling a brief that is already published leaves the live post as it is until that time, then updates it."},"external_url":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"External Url","description":"Canonical URL where the content was published. Only used when `target_type` is `external`."},"replace_site_edits":{"type":"boolean","title":"Replace Site Edits","description":"Send even though the post was edited on the site (for example in WordPress) after it was last sent from here; those edits are replaced. Without it such a send is refused with `validation_error` and `details.reason` `post_edited_on_site` (with `edited_at` and `sent_at`), so a person can decide.","default":false}},"additionalProperties":false,"type":"object","title":"ContentBriefPublish","description":"Where to publish a finished content brief."},"ContentBriefSummary":{"properties":{"object":{"type":"string","const":"content_brief","title":"Object","description":"Always `content_brief`.","default":"content_brief"},"id":{"type":"string","title":"Id","description":"Content brief id (UUID)."},"brand_id":{"type":"string","title":"Brand Id","description":"Owning brand id (UUID)."},"status":{"type":"string","enum":["draft","processing","needs_review","published","failed"],"title":"Status","description":"Brief lifecycle state. One of `draft`, `processing`, `needs_review`, `published`, `failed`."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"Brief title, set on creation or filled in from the article."},"topic":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Topic","description":"Topic or target keyword the content is written around."},"content_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content Type","description":"Content format id (e.g. `blog_post`, `ranked_list`)."},"mode":{"type":"string","enum":["create","optimize"],"title":"Mode","description":"`create` writes a new article; `optimize` improves the page at `source_url` (`content-optimizations`).","default":"create"},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Url","description":"The brand's own page an `optimize` brief improves."},"optimize_level":{"anyOf":[{"type":"string","enum":["conservative","balanced","full"]},{"type":"null"}],"title":"Optimize Level","description":"How far an `optimize` brief goes; null for `create`."},"target_keywords":{"items":{"type":"string"},"type":"array","title":"Target Keywords","description":"Target keywords for the brief."},"content_context":{"additionalProperties":true,"type":"object","title":"Content Context","description":"The format's own fields (the ones a content opportunity pre-fills, e.g. `listTheme` and `listSize` for `ranked_list`), plus `sources`: `{\"urls\": [...], \"only_mine\": false}`, up to 10 pages or PDFs the article reads before writing and cites, each reported in `quality_report.enforcement.sources` as `used`, `not_used` or `source_unreadable` (`only_mine: true` turns web search off and unwraps any other outside link), `sourcePrompts`: ids of the report prompts the article answers, and `length`: `{\"mode\": \"auto\"|\"short\"|\"standard\"|\"long\"}` or `{\"mode\": \"exact\", \"words\": 300-5000}` (omitted: the brand's `default_length`), and `blockedWords`: up to 100 phrases of up to 100 characters this article must not use on top of the brand's `banned_phrases`, and `knowledge`: `{\"mode\": \"auto\"}` (the knowledge base chunks closest to the topic, the default), `{\"mode\": \"pick\", \"ids\": [...]}` (only those knowledge base items) or `{\"mode\": \"off\"}`. This article only: `language` (a language name, over the brand's), `tone` (up to 200 characters, over the brand's), `audience` (who it is written for, up to 200 characters) and `tools` (`{tool: on|off|auto}` over the brand's AI tools, see content preferences). Other keys are ignored; the brand's banned phrases stay in its preferences."},"generated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Generated At","description":"When content was last generated, if ever."},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message","description":"User-facing failure reason when `status` is `failed`."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the brief was created."},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Updated At","description":"When the brief was last updated."},"quality_report":{"anyOf":[{"additionalProperties":true,"type":"object"},{"items":{},"type":"array"},{"type":"null"}],"title":"Quality Report","description":"Rule-based checks run on the finished article: `{score, axes[], checks[], notes[], words, language, link_check}`, where `score` is the percentage of weighted checks that passed. `link_check` is the source check run after writing: `checked` (how many external links were fetched), `removed[]` (links unwrapped because the page is gone: `url`, `reason`, `status`), `warnings[]` (links kept but worth a look, each `{url, reason}`: `moved_to_root` when a deep link now lands on the site's home page, with the `final_url` it landed on, `unverified` when the research never read the page) and `unverified_claims[]` (`{sentence, numbers[], urls[], reason}`, `reason` being `not_on_source` when the cited page does not carry the figures, `source_removed` when every cited link was removed, `source_unreadable` when no cited page could be read). Advisory only; it never blocks publishing."},"review_due_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Review Due At","description":"When the article's fastest-ageing fact (a price, a plan tier) is worth re-checking."},"planned_publish_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Planned Publish At","description":"The day the article sits on in the content calendar until it is published or a publish is queued; null when it has none. Set it with `PATCH /v1/brands/{brand_id}/content-briefs/{brief_id}`."},"publications":{"items":{"$ref":"#/components/schemas/ContentPublication"},"type":"array","title":"Publications","description":"Every place the article was published, with its live URL. Empty until it is published."},"market":{"anyOf":[{"$ref":"#/components/schemas/ContentBriefMarket"},{"type":"null"}],"description":"The market its source prompts were asked in, when they share one (a brief created from a missed prompt or a report gap of that market); null otherwise, and the article writes for the brand's own country."}},"additionalProperties":false,"type":"object","required":["id","brand_id","status","created_at"],"title":"ContentBriefSummary","description":"A content brief as it appears in a list, without the generated assets and heavy research fields."},"ContentBriefUpdate":{"properties":{"planned_publish_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Planned Publish At","description":"When the article is meant to go live (ISO 8601); `null` or an empty string takes its date away and it waits undated. Nothing publishes from it: it places the article on the calendar and prefills its publish schedule."}},"additionalProperties":false,"type":"object","required":["planned_publish_at"],"title":"ContentBriefUpdate","description":"Date an article on the content calendar, or take its date away."},"ContentCalendar":{"properties":{"object":{"type":"string","const":"content_calendar","title":"Object","description":"Always `content_calendar`.","default":"content_calendar"},"from":{"type":"string","format":"date-time","title":"From","description":"Start of the window read."},"to":{"type":"string","format":"date-time","title":"To","description":"End of the window read (exclusive)."},"slots":{"items":{"$ref":"#/components/schemas/CalendarSlot"},"type":"array","title":"Slots","description":"Every article slot in the window, in time order."},"articles":{"items":{"$ref":"#/components/schemas/CalendarArticle"},"type":"array","title":"Articles","description":"The articles the slots belong to."},"tasks":{"items":{"$ref":"#/components/schemas/Task"},"type":"array","title":"Tasks","description":"Open tasks due inside the window."},"autopilot_next_run_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Autopilot Next Run At","description":"When the brand's autopilot runs next, if it is on."}},"additionalProperties":false,"type":"object","required":["from","to","slots","articles","tasks"],"title":"ContentCalendar","description":"Every article slot and open task due date of a brand inside a window.","example":{"articles":[],"from":"2026-10-01T00:00:00+00:00","object":"content_calendar","slots":[{"approved":true,"at":"2026-10-14T09:00:00+00:00","brief_id":"8d0e2b7c-3f41-4b9a-a6c2-51f0d3e9b7a1","id":"8d0e2b7c-3f41-4b9a-a6c2-51f0d3e9b7a1","object":"calendar_slot","source":"brief","state":"planned","task_id":"4a1f0c55-8b4e-4b8e-9d3a-0e6c2f7d1b90","task_status":"approved"}],"tasks":[],"to":"2026-11-12T00:00:00+00:00"}},"PromptContentInProgress":{"properties":{"kind":{"type":"string","enum":["proposal","article","new_page","task"],"title":"Kind","description":"`proposal`: a Website autopilot change on the page; `article`: an article being written or waiting to be published; `new_page`: a page Website autopilot plans or is making; `task`: an open task."},"id":{"type":"string","title":"Id","description":"The change set, content brief, new page or task id."},"work_type":{"type":"string","title":"Work Type","description":"What it does: `improve_page`, `improve_article`, `article` or `new_page`."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"Its title, when it has one."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"The page it changes, or the address it will have."}},"additionalProperties":false,"type":"object","required":["kind","id","work_type"],"title":"PromptContentInProgress","description":"Work already under way on a prompt's page or topic, so the same thing is not started twice."},"ContentInterlink":{"properties":{"object":{"type":"string","const":"content_interlink","title":"Object","description":"Always `content_interlink`.","default":"content_interlink"},"id":{"type":"string","title":"Id","description":"Proposal id (UUID)."},"brief_id":{"type":"string","title":"Brief Id","description":"The article the link points to."},"article_url":{"type":"string","title":"Article Url","description":"The live URL of the article."},"target_url":{"type":"string","title":"Target Url","description":"The post the sentence is added to."},"target_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Title","description":"The post's title."},"context":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Context","description":"The paragraph of the post the sentence follows."},"sentence":{"type":"string","title":"Sentence","description":"The sentence added to the post, with `anchor` as the link text."},"anchor":{"type":"string","title":"Anchor","description":"The words of `sentence` that carry the link."},"similarity":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Similarity","description":"How related the post is to the article, 0 to 1."},"status":{"type":"string","enum":["proposed","applied","dismissed","task"],"title":"Status","description":"`proposed` (waiting for a decision), `applied` (the public page links to the article), `dismissed`, or `task` (the site cannot be edited from here, or its public page does not show the edit, so a task with the sentence was opened instead)."},"applied_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Applied At","description":"When the link was added to the post."},"task_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task Id","description":"The task that carries the sentence, for `task`."},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Why the last attempt to add the link failed."},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Created At","description":"When the proposal was made."}},"additionalProperties":false,"type":"object","required":["id","brief_id","article_url","target_url","sentence","anchor","status"],"title":"ContentInterlink","description":"A related post on the same site, the sentence that would link it to the article, and where that stands."},"ContentInterlinkList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/ContentInterlink"},"type":"array","title":"Data"}},"additionalProperties":false,"type":"object","required":["data"],"title":"ContentInterlinkList","description":"Every proposal for one article, most related first; a handful per article, so not paginated."},"ContentOpportunity":{"properties":{"object":{"type":"string","const":"content_opportunity","title":"Object","description":"Always `content_opportunity`.","default":"content_opportunity"},"id":{"type":"string","title":"Id","description":"Stable opportunity id (e.g. `prompt:<uuid>` or `competitor:<name>`). Not a UUID."},"kind":{"type":"string","enum":["missed_prompt","competitor","keyword_gap","search_console","tracked_keyword"],"title":"Kind","description":"Opportunity source. `missed_prompt` = a prompt where the brand is absent from AI answers; `competitor` = a competitor cited across many prompts where the brand is not; `keyword_gap` = a keyword a competitor ranks for in Google and the brand does not (from the cached keyword gap); `search_console` = a query the site already earns impressions for on page two or without the click; `tracked_keyword` = a tracked keyword no page of the brand ranks for."},"source":{"type":"string","title":"Source","description":"Human label of `kind`.","default":""},"score":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Score","description":"Priority from 0 to 100 built only from data the account already holds: demand (search volume or impressions), where the brand loses today, Google and AI difficulty, and fit. Halved when a brief already covers it.","default":0},"score_reasons":{"items":{"type":"string"},"type":"array","title":"Score Reasons","description":"Why the score is what it is, in order."},"title":{"type":"string","title":"Title","description":"The opportunity's headline: the keyword or the rival for those gaps, and for a missed prompt or a report gap the whole prompt as it was asked."},"reason":{"type":"string","title":"Reason","description":"One-line explanation of why this opportunity matters."},"content_type":{"type":"string","title":"Content Type","description":"Suggested content format id (e.g. `blog_post`, `comparative_article`)."},"topic":{"type":"string","title":"Topic","description":"Suggested topic or source prompt text (may be empty for competitor gaps)."},"target_keywords":{"items":{"type":"string"},"type":"array","title":"Target Keywords","description":"Suggested target keywords for the generated brief."},"content_context":{"additionalProperties":true,"type":"object","title":"Content Context","description":"Free-form pre-filled context passed through to content generation."},"competitor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Competitor","description":"Top competitor cited instead of the brand, when applicable."},"platforms_missed":{"items":{"type":"string"},"type":"array","title":"Platforms Missed","description":"Display labels of the AI platforms where the brand is absent for this prompt."},"has_existing_brief":{"type":"boolean","title":"Has Existing Brief","description":"True when a content brief already covers this opportunity."},"metrics":{"$ref":"#/components/schemas/ContentOpportunityMetrics","description":"Search demand, difficulty and Search Console numbers behind the score, as numbers to weigh on your side. The same facts appear in `score_reasons` as prose."},"places":{"items":{"$ref":"#/components/schemas/ContentOpportunityPlace"},"type":"array","title":"Places","description":"The markets its prompts were asked in (a missed prompt, a competitor, a report gap). Empty for a brand wide source: keyword gap, Search Console and tracked keywords. A brief created from it writes for that market when there is one."}},"additionalProperties":false,"type":"object","required":["id","kind","title","reason","content_type","topic","has_existing_brief"],"title":"ContentOpportunity","description":"A report-driven content idea: a missed prompt or a competitor gap.","example":{"competitor":"Asana","content_context":{"listSize":7,"listTheme":"project management tools for agencies"},"content_type":"ranked_list","has_existing_brief":false,"id":"prompt:9a17c4f8-4e31-92fa-7d1e-3b5c8b2a9a17","kind":"missed_prompt","metrics":{"ai_difficulty":58,"keyword_difficulty":34,"object":"content_opportunity_metrics","search_volume":1900},"object":"content_opportunity","places":[{"city":"Austin","country":"United States","language":"English","object":"content_opportunity_place","place_key":"united states|austin"}],"platforms_missed":["ChatGPT","Perplexity"],"reason":"You are absent on ChatGPT, Perplexity; Asana is cited instead.","score":71,"score_reasons":["1,900 searches a month","Absent on 2 of 3 AI engines","Asana is cited instead"],"source":"Missed prompt","target_keywords":["best project management tools for agencies"],"title":"best project management tools for agencies","topic":"What are the best project management tools for agencies?"}},"ContentOpportunityList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/ContentOpportunity"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"True when more items exist past this page. Fetch them with a larger `offset`."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of items matching the query, across all pages."},"limit":{"type":"integer","minimum":1.0,"title":"Limit","description":"Page size that was applied."},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of items skipped before this page."},"summary":{"$ref":"#/components/schemas/ContentOpportunitySummary"}},"additionalProperties":false,"type":"object","required":["data","has_more","total","limit","offset","summary"],"title":"ContentOpportunityList","description":"A page of the opportunities ranked by impact, plus a `summary`; page with `offset` while `has_more`.","example":{"data":[{"competitor":"Asana","content_context":{"listSize":7,"listTheme":"project management tools for agencies"},"content_type":"ranked_list","has_existing_brief":false,"id":"prompt:9a17c4f8-4e31-92fa-7d1e-3b5c8b2a9a17","kind":"missed_prompt","metrics":{"ai_difficulty":58,"keyword_difficulty":34,"object":"content_opportunity_metrics","search_volume":1900},"object":"content_opportunity","places":[{"city":"Austin","country":"United States","language":"English","object":"content_opportunity_place","place_key":"united states|austin"}],"platforms_missed":["ChatGPT","Perplexity"],"reason":"You are absent on ChatGPT, Perplexity; Asana is cited instead.","score":71,"score_reasons":["1,900 searches a month","Absent on 2 of 3 AI engines","Asana is cited instead"],"source":"Missed prompt","target_keywords":["best project management tools for agencies"],"title":"best project management tools for agencies","topic":"What are the best project management tools for agencies?"}],"has_more":false,"limit":24,"object":"list","offset":0,"summary":{"actionable":21,"competitors":6,"missed_prompts":42,"object":"content_opportunity_summary","opportunities":24,"prompts_analyzed":137,"reports_analyzed":10,"total":57},"total":1}},"ContentOpportunityMetrics":{"properties":{"object":{"type":"string","const":"content_opportunity_metrics","title":"Object","description":"Always `content_opportunity_metrics`.","default":"content_opportunity_metrics"},"search_volume":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Search Volume","description":"Monthly Google searches for the target keyword."},"keyword_difficulty":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Keyword Difficulty","description":"Google keyword difficulty from 0 to 100 for the target keyword."},"ai_difficulty":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Ai Difficulty","description":"How entrenched the AI answers are for this question, from 0 to 100. Higher is harder to win."},"impressions":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Impressions","description":"Search Console impressions the site already earns for this query."},"position":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Position","description":"Average Search Console position for this query."}},"additionalProperties":false,"type":"object","title":"ContentOpportunityMetrics","description":"Google and AI numbers behind an opportunity, read from what the account already holds. Null when unknown."},"ContentOpportunityPlace":{"properties":{"object":{"type":"string","const":"content_opportunity_place","title":"Object","description":"Always `content_opportunity_place`.","default":"content_opportunity_place"},"place_key":{"type":"string","title":"Place Key","description":"`country|city` lowercased (`country|city|region` for a town keyed apart from its namesake): the value the `place` filter takes."},"country":{"type":"string","title":"Country","description":"The market's country."},"city":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"City","description":"The market's city as Google spells it (the city of its place_key); null for a country."},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language","description":"The language the market asks in."}},"additionalProperties":false,"type":"object","required":["place_key","country"],"title":"ContentOpportunityPlace","description":"A market an opportunity's prompts were asked in."},"ContentOpportunitySummary":{"properties":{"object":{"type":"string","const":"content_opportunity_summary","title":"Object","description":"Always `content_opportunity_summary`.","default":"content_opportunity_summary"},"missed_prompts":{"type":"integer","minimum":0.0,"title":"Missed Prompts","description":"Distinct prompts where the brand is absent from AI answers."},"competitors":{"type":"integer","minimum":0.0,"title":"Competitors","description":"Distinct competitors cited where the brand is absent."},"opportunities":{"type":"integer","minimum":0.0,"title":"Opportunities","description":"Opportunities returned in `data` (bounded by `limit`)."},"total":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Total","description":"Opportunities matching the `kind` filter across the whole stored set. Page with `offset`."},"actionable":{"type":"integer","minimum":0.0,"title":"Actionable","description":"Opportunities in the whole stored set, of any kind, not yet covered by a brief."},"reports_analyzed":{"type":"integer","minimum":0.0,"title":"Reports Analyzed","description":"Recent reports scanned to build these opportunities."},"prompts_analyzed":{"type":"integer","minimum":0.0,"title":"Prompts Analyzed","description":"Prompts actually examined across those reports."},"computed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Computed At","description":"When this set was last computed."},"refresh_available":{"type":"boolean","title":"Refresh Available","description":"`true` when the data the set was built from has moved since `computed_at` (a new report, a Search Console or keyword gap refresh, tracked keywords or articles changed).","default":false}},"additionalProperties":false,"type":"object","required":["missed_prompts","competitors","opportunities","actionable","reports_analyzed","prompts_analyzed"],"title":"ContentOpportunitySummary","description":"Aggregate counts for the opportunity set.","example":{"actionable":21,"competitors":6,"missed_prompts":42,"object":"content_opportunity_summary","opportunities":24,"prompts_analyzed":137,"reports_analyzed":10,"total":57}},"ContentOptimizationCreate":{"properties":{"source_url":{"type":"string","maxLength":2000,"title":"Source Url","description":"The page to improve, on the brand's own website."},"optimize_level":{"type":"string","enum":["conservative","balanced","full"],"title":"Optimize Level","description":"`conservative` changes only what an issue asks for and adds sections, every other sentence stays; `balanced` may rewrite any section, keeping its headings and their order; `full` rewrites the page with the live page as a source it must use.","default":"balanced"},"target_keywords":{"items":{"type":"string"},"type":"array","maxItems":20,"title":"Target Keywords","description":"Keywords the page should win; the first leads."},"source_prompt_ids":{"items":{"type":"string"},"type":"array","maxItems":50,"title":"Source Prompt Ids","description":"Report prompts the page should win back, so the citation uplift can say which came back."},"reference_urls":{"items":{"type":"string"},"type":"array","maxItems":9,"title":"Reference Urls","description":"Up to 9 more pages or PDFs to read and cite, for example the pages AI cites for those prompts (`GET /v1/brands/{brand_id}/prompts/{prompt_hash}/cited-pages`)."},"content_context":{"additionalProperties":true,"type":"object","title":"Content Context","description":"`language`, `tone` and `audience` (up to 200 characters each), `blockedWords`, `tools` and `knowledge`, as in a brief's `content_context`."}},"additionalProperties":false,"type":"object","required":["source_url"],"title":"ContentOptimizationCreate","description":"Improve a page the brand already publishes: read it, find what holds it back, fix it at a level."},"ContentPlan":{"properties":{"object":{"type":"string","const":"content_plan","title":"Object","default":"content_plan"},"batch_id":{"type":"string","title":"Batch Id"},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Articles in the plan.","default":0},"queued":{"type":"integer","minimum":0.0,"title":"Queued","description":"Articles still waiting or being written.","default":0},"ready":{"type":"integer","minimum":0.0,"title":"Ready","description":"Articles finished and waiting for a read.","default":0},"failed":{"type":"integer","minimum":0.0,"title":"Failed","default":0},"done":{"type":"boolean","title":"Done","description":"True when nothing is left running.","default":false},"already_queued":{"type":"boolean","title":"Already Queued","description":"This batch_id had already been queued, so nothing was charged again.","default":false},"credits_charged":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Credits Charged","description":"Only on the call that queued the plan."},"articles":{"items":{"$ref":"#/components/schemas/ContentPlanArticle"},"type":"array","title":"Articles"}},"additionalProperties":false,"type":"object","required":["batch_id"],"title":"ContentPlan","description":"A batch of articles queued together, with one balance check for the whole plan."},"ContentPlanArticle":{"properties":{"object":{"type":"string","const":"content_plan_article","title":"Object","default":"content_plan_article"},"brief_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brief Id","description":"Null for an article that could not be queued."},"job_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Id","description":"Poll it like any job; it equals `brief_id`."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"topic":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Topic"},"content_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content Type"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status","description":"The brief's status, e.g. `processing`, `needs_review`."},"step":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Step","description":"Where the pipeline is, while it runs."},"opportunity_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Opportunity Id","description":"The opportunity this article answers."},"planned_publish_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Planned Publish At"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Why this one did not queue, or why it failed."}},"additionalProperties":false,"type":"object","title":"ContentPlanArticle","description":"One article of a plan, and how far it has got."},"ContentPlanCreate":{"properties":{"items":{"anyOf":[{"items":{"$ref":"#/components/schemas/ContentPlanItem"},"type":"array","maxItems":30,"minItems":1},{"type":"null"}],"title":"Items","description":"Up to 30 articles, 10 credits each. Pass `items` or `cluster_id`, not both."},"cluster_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cluster Id","description":"Plan a keyword cluster (`GET /v1/brands/{brand_id}/seo/keyword-clusters`) instead of listing items: its pillar first unless it already has an article, then up to 29 of its most searched keywords without one. Each support article links to the pillar article once that one is live."},"batch_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Batch Id","description":"Your own id for the batch, so a retry cannot queue (and charge) the same plan twice."}},"additionalProperties":false,"type":"object","title":"ContentPlanCreate","description":"Generate several articles at once, each on the single-article contract."},"ContentPlanItem":{"properties":{"title":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Title","description":"Optional title; the generator fills one in when omitted."},"topic":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Topic","description":"Topic or target keyword to write about. Provide this or at least one `target_keywords` entry."},"target_keywords":{"items":{"type":"string"},"type":"array","maxItems":20,"title":"Target Keywords","description":"Target keywords to write around (each up to 200 chars)."},"content_type":{"anyOf":[{"type":"string","enum":["blog_post","comparative_article","ranked_list","geo_spotlight","case_study","product_deep_dive","faq_article","citation_faq","statistics_roundup","glossary","how_to","landing_page","product_page"]},{"type":"null"}],"title":"Content Type","description":"Content format to generate; inferred from the topic when omitted."},"source_prompt_ids":{"items":{"type":"string"},"type":"array","maxItems":50,"title":"Source Prompt Ids","description":"Report prompts this article is written to answer. They are snapshotted now, so the citation uplift can later say which of them came back."},"content_context":{"additionalProperties":true,"type":"object","title":"Content Context","description":"The format's own fields (the ones a content opportunity pre-fills, e.g. `listTheme` and `listSize` for `ranked_list`), plus `sources` (see the brief's `content_context`), and `length`, `knowledge`, `language`, `tone`, `audience` and `tools` (see the brief's `content_context`). Those keys are checked: an unknown `language`, a `tone` or `audience` over 200 characters, a tool or mode outside the lists, or a source that is not an http(s) address answers 422. Other keys are ignored."},"opportunity_id":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}],"title":"Opportunity Id","description":"The `id` of the content opportunity this article answers."},"planned_publish_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Planned Publish At","description":"When it should go live. It prefills the CMS schedule; nothing fires from it."}},"additionalProperties":false,"type":"object","title":"ContentPlanItem","description":"One article of a plan: the same body as a single brief."},"ContentPreferences":{"properties":{"object":{"type":"string","const":"content_preferences","title":"Object","default":"content_preferences"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language","description":"Language to write in; the brand's own when null."},"tone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tone","description":"How it should sound, in your words."},"writing_style":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Writing Style","description":"Structure and habits: length, lists, tables."},"image_style":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Style","description":"How generated images should look."},"banned_phrases":{"items":{"type":"string"},"type":"array","title":"Banned Phrases","description":"Phrases the article must not use, whatever the topic."},"auto_interlink":{"type":"boolean","title":"Auto Interlink","description":"When true, every article of this brand that goes live gets links back from its related posts on the same site, applied right away where the destination can edit a post; other sites get a task. When false the proposed links wait for review.","default":false},"recheck_source_prompts":{"type":"boolean","title":"Recheck Source Prompts","description":"When true, the prompts each article was written for run again 14 and 28 days after it went live, in the market and on the engines they were measured in, as a one-off report named after the article. Each run is charged like any run. Needs the brand owner on Starter or above.","default":false},"default_length":{"type":"string","enum":["auto","short","standard","long"],"title":"Default Length","description":"How long articles run unless a brief sets `content_context.length`. `auto` follows the median length of the readable top Google results for the keyword (times 1.1); `short`, `standard` and `long` are about 800, 1,500 and 2,500 words. All of them are held inside the content type's bounds.","default":"auto"},"voice_profile":{"anyOf":[{"$ref":"#/components/schemas/VoiceProfile"},{"type":"null"}],"description":"The voice learned from the brand's own posts, or null before it is learned. Generation does not read it: copy what fits into `writing_style` and `banned_phrases`."},"voice_extracted_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Voice Extracted At","description":"When the voice was last learned."},"tools":{"additionalProperties":{"type":"string","enum":["on","off","auto"]},"propertyNames":{"enum":["web_search","google_news","internal_links","crawl_site","featured_image","screenshots","reference_pages","knowledge_base"]},"type":"object","title":"Tools","description":"The brand's default for each AI tool its articles may use: `on`, `off` or `auto` (the run decides from the format, the site index, the knowledge base and the results page). A tool not listed is `auto`. A brief overrides any of them in `content_context.tools`."}},"additionalProperties":false,"type":"object","title":"ContentPreferences","description":"How this brand's articles should read. The generator follows it on every article.","example":{"auto_interlink":true,"banned_phrases":["game changer","in today's fast-paced world"],"default_length":"auto","image_style":"Flat illustration, purple accents","language":"English","object":"content_preferences","recheck_source_prompts":false,"tone":"Direct and technical, no hype","writing_style":"Short paragraphs, real numbers, a table when comparing"}},"ContentPreferencesUpdate":{"properties":{"language":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"title":"Language"},"tone":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Tone"},"writing_style":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Writing Style"},"image_style":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Image Style"},"banned_phrases":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":100},{"type":"null"}],"title":"Banned Phrases","description":"Up to 100 phrases, each up to 200 characters."},"auto_interlink":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Auto Interlink","description":"Apply the proposed links back to every article of this brand that goes live."},"recheck_source_prompts":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Recheck Source Prompts","description":"Run each live article's source prompts again 14 and 28 days after it went live (Starter, charged)."},"default_length":{"anyOf":[{"type":"string","enum":["auto","short","standard","long"]},{"type":"null"}],"title":"Default Length","description":"Default article length: auto, short, standard or long."},"tools":{"anyOf":[{"additionalProperties":{"type":"string","enum":["on","off","auto"]},"propertyNames":{"enum":["web_search","google_news","internal_links","crawl_site","featured_image","screenshots","reference_pages","knowledge_base"]},"type":"object"},{"type":"null"}],"title":"Tools","description":"AI tool defaults to set, for example `{\"google_news\": \"on\", \"screenshots\": \"off\"}`: the whole map is replaced by what you send."}},"additionalProperties":false,"type":"object","title":"ContentPreferencesUpdate","description":"Change what you send; the rest stays as it is. A field sent as `null` is cleared."},"ContentPublication":{"properties":{"object":{"type":"string","const":"content_publication","title":"Object","description":"Always `content_publication`.","default":"content_publication"},"target_type":{"type":"string","enum":["cms_connection","hosted_site","external"],"title":"Target Type","description":"Where the article went."},"target_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Id","description":"The CMS connection or hosted site id; null for `external`."},"status":{"type":"string","title":"Status","description":"`published`, `scheduled`, `held` (its time came while the brand owner's plan did not include publishing: it goes out when the plan is back if its time is still ahead), `missed` (its time passed while it was `held`: it never goes out on its own, move it to a new `run_at` or cancel it), `draft` (saved on the target as a draft, or a new post waiting for its pull request) or `failed`. An update of a live post sent as a pull request stays `published`, with `review_url` set until the pull request merges."},"published_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Published Url","description":"The live URL of the article."},"published_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Published At","description":"When it went live."},"scheduled_for":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Scheduled For","description":"When a `scheduled` post goes live next; a retry after a failed attempt moves it."},"schedule_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Schedule Id","description":"The queued publish while `status` is `scheduled`, `held` or `missed`; move it with `PATCH /v1/brands/{brand_id}/content-briefs/{brief_id}/publish-schedules/{schedule_id}` or cancel it with `DELETE` on the same path."},"review_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Review Url","description":"The pull request a `github` target opened for the post, until it merges or closes. Merging it makes the post live, or puts the new version live when the post already was; a draft pull request holds a draft."},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Note","description":"What the last send could not do as asked, in the brand owner's language: the blocks Wix dropped, a site that kept the post unpublished, or a deleted post sent again as a new one. Null when there is nothing to say."}},"additionalProperties":false,"type":"object","required":["target_type","status"],"title":"ContentPublication","description":"Where a brief was published, and whether it is live."},"CopilotCitationList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/CopilotCitedPage"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Opaque continuation token. Pass back as `?cursor=` to fetch the next page. `null` when `has_more` is false."}},"additionalProperties":false,"type":"object","required":["data","has_more"],"title":"CopilotCitationList","description":"Cursor-paginated cited pages of one uploaded Bing AI Performance export, most citations first.","example":{"data":[{"citations":81,"id":"0b6f8c1e-5d2a-4c1f-9a7e-2f4b1d3c5e6a","object":"copilot_cited_page","page":"https://rankprompt.com/best-ai-search-visibility-tracking-tools/","period_end":"2026-10-19","period_start":"2026-10-18","seen_by":[{"citations":5,"engine":"chatgpt","last_seen":"2026-10-20T14:02:11+00:00","object":"copilot_engine_seen"}]}],"has_more":false,"object":"list"}},"CopilotCitedPage":{"properties":{"object":{"type":"string","const":"copilot_cited_page","title":"Object","default":"copilot_cited_page"},"id":{"type":"string","title":"Id","description":"The row's id."},"page":{"type":"string","title":"Page","description":"The page, as Bing wrote it in the export."},"citations":{"type":"integer","minimum":0.0,"title":"Citations","description":"Times Copilot cited it in the period, per Bing."},"period_start":{"type":"string","title":"Period Start","description":"First day the uploaded export covers (YYYY-MM-DD)."},"period_end":{"type":"string","title":"Period End","description":"Last day it covers (YYYY-MM-DD)."},"seen_by":{"items":{"$ref":"#/components/schemas/CopilotEngineSeen"},"type":"array","title":"Seen By","description":"Engines whose answers in the brand's completed reports cited the same page, most first; empty when none did."}},"additionalProperties":false,"type":"object","required":["id","page","citations","period_start","period_end","seen_by"],"title":"CopilotCitedPage","description":"A page Bing says Copilot cited in the period, with the engines the brand's reports saw cite it too.","example":{"citations":81,"id":"0b6f8c1e-5d2a-4c1f-9a7e-2f4b1d3c5e6a","object":"copilot_cited_page","page":"https://rankprompt.com/best-ai-search-visibility-tracking-tools/","period_end":"2026-10-19","period_start":"2026-10-18","seen_by":[{"citations":5,"engine":"chatgpt","last_seen":"2026-10-20T14:02:11+00:00","object":"copilot_engine_seen"}]}},"CopilotEngineSeen":{"properties":{"object":{"type":"string","const":"copilot_engine_seen","title":"Object","default":"copilot_engine_seen"},"engine":{"type":"string","title":"Engine","description":"The engine that cited it in the brand's reports (an open set, e.g. `chatgpt`)."},"citations":{"type":"integer","minimum":0.0,"title":"Citations","description":"Answers of that engine, in completed reports, that cited the page."},"last_seen":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Last Seen","description":"When a report last saw it cited."}},"additionalProperties":false,"type":"object","required":["engine","citations"],"title":"CopilotEngineSeen","description":"An engine Rank Prompt's own reports saw cite the same page."},"CreateBrandRequest":{"properties":{"name":{"type":"string","maxLength":150,"minLength":1,"title":"Name","description":"Display name (1-150 chars)."},"website":{"type":"string","maxLength":500,"title":"Website","description":"Primary brand website URL. Required. Must be a fully-qualified `http(s)://` URL."},"language":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"title":"Language","description":"Primary language. Accepts English name (`English`, `Spanish`) or ISO 639-1 code (`en`, `es`); normalised to the English name on write."},"country":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Country","description":"Primary country (e.g. `United States`, `Argentina`)."},"brand_aliases":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":50},{"type":"null"}],"title":"Brand Aliases","description":"Up to 50 alternate names used for citation matching. Names that differ only in case or spacing are kept once, with the first spelling sent."},"categories":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":30},{"type":"null"}],"title":"Categories","description":"Free-form industry/topic tags (e.g. `running shoes`, `saas`). Up to 30 entries, each up to 100 characters. Defaults to `[]` on create."}},"additionalProperties":false,"type":"object","required":["name","website"],"title":"CreateBrandRequest","description":"Body for ``POST /v1/brands``.","example":{"brand_aliases":["adidas Originals","adidas AG"],"categories":["running shoes","sportswear"],"country":"United States","language":"English","name":"adidas","website":"https://www.adidas.com"}},"CreditBalance":{"properties":{"object":{"type":"string","const":"credit_balance","title":"Object","description":"Always `credit_balance`.","default":"credit_balance"},"available":{"type":"integer","minimum":0.0,"title":"Available","description":"Credits available to spend now (`total` minus `reserved`)."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total credits left across all pools."},"reserved":{"type":"integer","minimum":0.0,"title":"Reserved","description":"Credits reserved by in-flight operations, not yet finalized."},"monthly_left":{"type":"integer","minimum":0.0,"title":"Monthly Left","description":"Credits left in the monthly plan allotment."},"api_addon_left":{"type":"integer","minimum":0.0,"title":"Api Addon Left","description":"Credits left in the API add-on pool."},"topup_left":{"type":"integer","minimum":0.0,"title":"Topup Left","description":"Credits left from one-off top-ups (do not expire monthly)."}},"additionalProperties":false,"type":"object","required":["available","total","reserved","monthly_left","api_addon_left","topup_left"],"title":"CreditBalance","description":"Your product-credit balance across the monthly, API add-on and top-up pools.","example":{"api_addon_left":0,"available":182,"monthly_left":150,"object":"credit_balance","reserved":8,"topup_left":40,"total":190}},"CreditPurchase":{"properties":{"object":{"type":"string","const":"credit_purchase","title":"Object","description":"Always `credit_purchase`.","default":"credit_purchase"},"status":{"type":"string","enum":["succeeded","checkout"],"title":"Status","description":"`succeeded` when the payment settled and the credits are on the balance. `checkout` when nothing was charged yet and the buyer must open `checkout_url`. Repeating the call for the same pack returns that same link while it is open, and `succeeded` once the buyer has paid it."},"pack":{"type":"string","enum":["small","medium","large"],"title":"Pack","description":"The pack that was bought."},"credits":{"type":"integer","minimum":0.0,"title":"Credits","description":"Credits the pack grants."},"amount_cents":{"type":"integer","minimum":0.0,"title":"Amount Cents","description":"Pack price in the smallest currency unit."},"currency":{"type":"string","title":"Currency","description":"ISO 4217 code, lowercase."},"payment_intent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Payment Intent Id","description":"The settled Stripe PaymentIntent, on `succeeded`."},"checkout_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Checkout Url","description":"Where the buyer completes the purchase, on `checkout`."},"checkout_session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Checkout Session Id","description":"The Stripe Checkout session, when the purchase goes or went through Checkout."}},"additionalProperties":false,"type":"object","required":["status","pack","credits","amount_cents","currency"],"title":"CreditPurchase","description":"The outcome of a credit purchase: paid, or waiting on a checkout.","example":{"amount_cents":1800,"credits":50,"currency":"usd","object":"credit_purchase","pack":"small","payment_intent_id":"pi_3AbCdEf...","status":"succeeded"}},"CreditPurchaseRequest":{"properties":{"pack":{"type":"string","enum":["small","medium","large"],"title":"Pack","description":"Which credit pack to buy: `small`, `medium` or `large`."},"shared_payment_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Shared Payment Token","description":"A Stripe shared payment token the buyer's agent wallet issued for this purchase. Given one, the charge settles on this call and the credits land immediately. Omit it to get a checkout link to hand the buyer instead."}},"additionalProperties":false,"type":"object","required":["pack"],"title":"CreditPurchaseRequest","description":"Buy a credit pack, paying now if the caller holds a payment token.","example":{"pack":"small","shared_payment_token":"spt_1AbC..."}},"CustomHeader":{"properties":{"name":{"type":"string","maxLength":100,"minLength":1,"title":"Name"},"value":{"type":"string","maxLength":1024,"minLength":1,"title":"Value"}},"additionalProperties":false,"type":"object","required":["name","value"],"title":"CustomHeader","description":"A header sent with every delivery next to the signature."},"DataExport":{"properties":{"object":{"type":"string","const":"data_export","title":"Object","default":"data_export"},"id":{"type":"string","title":"Id","description":"Export id."},"brand_id":{"type":"string","title":"Brand Id","description":"The brand exported."},"status":{"type":"string","enum":["queued","running","completed","failed","expired"],"title":"Status","description":"`queued`, `running`, `completed` (files ready), `failed` (ask again with the same body to resume where it stopped) or `expired` (files deleted 24 hours after completing)."},"datasets":{"items":{"type":"string","enum":["citations","answers"]},"type":"array","title":"Datasets","description":"The datasets asked for."},"filters":{"$ref":"#/components/schemas/DataExportFilters"},"format":{"type":"string","const":"ndjson","title":"Format","description":"One JSON object per line.","default":"ndjson"},"compression":{"type":"string","const":"gzip","title":"Compression","description":"Every file is gzipped.","default":"gzip"},"progress_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Progress Pct","description":"How far the export got, by the time span read so far."},"row_count":{"type":"integer","minimum":0.0,"title":"Row Count","description":"Rows written across datasets."},"byte_count":{"type":"integer","minimum":0.0,"title":"Byte Count","description":"Gzipped bytes written across files."},"results":{"items":{"$ref":"#/components/schemas/DataExportResult"},"type":"array","title":"Results","description":"One entry per dataset asked for."},"links_expire_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Links Expire At","description":"When the file links stop working."},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Why the export failed, when it did."},"created_at":{"type":"string","format":"date-time","title":"Created At"},"started_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Started At"},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Completed At"},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Expires At","description":"When the files are deleted."}},"additionalProperties":false,"type":"object","required":["id","brand_id","status","datasets","filters","progress_pct","row_count","byte_count","results","created_at"],"title":"DataExport","description":"An export of a brand's citation and answer history into downloadable files.","example":{"brand_id":"5ddd550e-10e0-50ea-80c8-2058f75229d3","byte_count":41943040,"completed_at":"2026-10-07T13:59:40+00:00","compression":"gzip","created_at":"2026-10-07T13:58:02+00:00","datasets":["citations","answers"],"expires_at":"2026-10-08T13:59:40+00:00","filters":{"date_from":"2026-07-01T00:00:00+00:00"},"format":"ndjson","id":"3f1c2b8e-6a0d-4c1e-9d2f-7b5a4e3c2d10","links_expire_at":"2026-10-07T14:15:00+00:00","object":"data_export","progress_pct":100,"results":[{"dataset":"citations","done":true,"files":[{"bytes":23068672,"rows":653453,"url":"/storage/v1/object/sign/data-exports/.../citations-0001.ndjson.gz?token=..."}],"rows":653453},{"dataset":"answers","done":true,"files":[{"bytes":18874368,"rows":111606,"url":"/storage/v1/object/sign/data-exports/.../answers-0001.ndjson.gz?token=..."}],"rows":111606}],"row_count":765059,"started_at":"2026-10-07T13:58:03+00:00","status":"completed"}},"CreateDataExportRequest":{"properties":{"datasets":{"items":{"type":"string","enum":["citations","answers"]},"type":"array","maxItems":2,"minItems":1,"title":"Datasets","description":"`citations`: one row per cited URL per answer. `answers`: one row per engine answer, full text included. Default both."},"report_id":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":100},{"type":"null"}],"title":"Report Id","description":"Only these reports (UUIDs)."},"tracker_id":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":100},{"type":"null"}],"title":"Tracker Id","description":"Only the runs of these trackers (a report's `tracker_id`; a Scheduled Report's id is its tracker's)."},"market_id":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":100},{"type":"null"}],"title":"Market Id","description":"Only the runs in these markets (a report's `market_id`)."},"place":{"anyOf":[{"items":{"type":"string","maxLength":300,"minLength":1},"type":"array","maxItems":200},{"type":"null"}],"title":"Place","description":"Only the runs in these places, as `country|city` lowercased (`united states|austin`, or `united states|` for the whole country; `country|city|region` for a town keyed apart from its namesake), across every tracker."},"platform":{"anyOf":[{"items":{"type":"string","enum":["chatgpt","chatgpt_search","perplexity","ai_overviews","claude","claude_search","gemini","grok","muse"]},"type":"array","maxItems":20},{"type":"null"}],"title":"Platform","description":"Only answers from these engines."},"date_from":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Date From","description":"Only answers from this moment on (ISO-8601)."},"date_to":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Date To","description":"Only answers before this moment, exclusive (ISO-8601)."},"scheduled_report_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scheduled Report Id","description":"Only the runs of this Scheduled Report."}},"additionalProperties":false,"type":"object","title":"CreateDataExportRequest","description":"What to export: the datasets, and the filters every row must match.","example":{"datasets":["citations","answers"],"date_from":"2026-07-01T00:00:00Z"}},"DataExportFile":{"properties":{"url":{"type":"string","title":"Url","description":"Signed download link, valid until `links_expire_at`. Read the export again for fresh links."},"rows":{"type":"integer","minimum":0.0,"title":"Rows","description":"Lines in the file."},"bytes":{"type":"integer","minimum":0.0,"title":"Bytes","description":"Size of the gzipped file."}},"additionalProperties":false,"type":"object","required":["url","rows","bytes"],"title":"DataExportFile","description":"One gzipped NDJSON file of a dataset: one JSON object per line."},"DataExportFilters":{"properties":{"report_id":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Report Id","description":"Only these reports."},"scheduled_report_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scheduled Report Id","description":"Only the runs of this Scheduled Report."},"tracker_id":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Tracker Id","description":"Only the runs of these trackers (a Scheduled Report's id is its tracker's)."},"market_id":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Market Id","description":"Only the runs in these markets."},"place":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Place","description":"Only the runs in these places (`country|city` or `country|city|region`)."},"platform":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Platform","description":"Only answers from these engines."},"date_from":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Date From","description":"Only answers from this moment on."},"date_to":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Date To","description":"Only answers before this moment, exclusive."}},"additionalProperties":false,"type":"object","title":"DataExportFilters","description":"The filters the export applies, normalized: ids lowercased and sorted, instants in UTC."},"DataExportResult":{"properties":{"dataset":{"type":"string","enum":["citations","answers"],"title":"Dataset","description":"`citations` or `answers`."},"rows":{"type":"integer","minimum":0.0,"title":"Rows","description":"Rows written so far; every row once the dataset is `done`."},"done":{"type":"boolean","title":"Done","description":"Whether the dataset was read to its end."},"files":{"items":{"$ref":"#/components/schemas/DataExportFile"},"type":"array","title":"Files","description":"The files in row order, oldest answer first, each at most 32 MiB gzipped. Empty until the export completes, and for a dataset with no rows."}},"additionalProperties":false,"type":"object","required":["dataset","rows","done","files"],"title":"DataExportResult","description":"One dataset of the export."},"DataStudioBrand":{"properties":{"brand_id":{"type":"string","title":"Brand Id","description":"The brand's id."},"brand_name":{"type":"string","title":"Brand Name","description":"The brand's name."},"brand_website":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brand Website","description":"The brand's website."},"client_company":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Client Company","description":"The client company the brand belongs to."},"tags":{"type":"string","title":"Tags","description":"The brand's tags, comma separated."},"date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Date","description":"Day of its newest run in the period (UTC); null when none."},"score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Score","description":"Visibility score of that run, its markets pooled, 0 to 100; null when none."}},"additionalProperties":false,"type":"object","required":["brand_id","brand_name","tags"],"title":"DataStudioBrand","description":"One brand of the account, with its newest score in the period."},"DataStudioBrandList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/DataStudioBrand"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Opaque continuation token. Pass back as `?cursor=` to fetch the next page. `null` when `has_more` is false."}},"additionalProperties":false,"type":"object","required":["data","has_more"],"title":"DataStudioBrandList","description":"A page of brands, newest first.","example":{"data":[{"brand_id":"20000000-0000-4000-8000-000000000001","brand_name":"adidas","brand_website":"https://www.adidas.com","client_company":"adidas AG","date":"2026-10-27","score":42.5,"tags":"retail, footwear"}],"has_more":false,"object":"list"}},"DataStudioCitation":{"properties":{"domain":{"type":"string","title":"Domain","description":"The cited domain."},"site_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Site Type","description":"The kind of site most of its cited pages are."},"citations":{"type":"integer","minimum":0.0,"title":"Citations","description":"Times answers cited a page of it."},"pages":{"type":"integer","minimum":0.0,"title":"Pages","description":"Distinct pages of it cited."},"with_backlink":{"type":"integer","minimum":0.0,"title":"With Backlink","description":"Cited pages of it that link to the brand."},"share":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Share","description":"Its percent of every citation in the period."},"avg_position":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Position","description":"Its mean position among an answer's citations."}},"additionalProperties":false,"type":"object","required":["domain","citations","pages","with_backlink"],"title":"DataStudioCitation","description":"One cited domain over the period, as the PDF report's citation sources list it."},"DataStudioCitationList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/DataStudioCitation"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"True when more items exist past this page. Fetch them with a larger `offset`."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of items matching the query, across all pages."},"limit":{"type":"integer","minimum":1.0,"title":"Limit","description":"Page size that was applied."},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of items skipped before this page."}},"additionalProperties":false,"type":"object","required":["data","has_more","total","limit","offset"],"title":"DataStudioCitationList","description":"A page of cited domains, most cited first.","example":{"data":[{"avg_position":2.4,"citations":38,"domain":"runnersworld.com","pages":9,"share":6.2,"site_type":"editorial","with_backlink":4}],"has_more":true,"limit":500,"object":"list","offset":0,"total":214}},"DataStudioCompetitor":{"properties":{"name":{"type":"string","title":"Name","description":"The name the competitor directory keeps."},"category":{"type":"string","title":"Category","description":"Its relation: `my_brand`, `direct_competitor`, `indirect_competitor`, `ai_platform`, `publisher` or `other`."},"website":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Website","description":"Its website, when known."},"is_own_brand":{"type":"boolean","title":"Is Own Brand","description":"True on the brand's own row."},"mentions":{"type":"integer","minimum":0.0,"title":"Mentions","description":"Answers that named it."},"share":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Share","description":"Its percent of every mention in the period."},"change":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Change","description":"Share in the newer half of the runs minus the older half, in points."},"platforms":{"type":"string","title":"Platforms","description":"The AI platforms that named it, comma separated."},"is_new":{"type":"boolean","title":"Is New","description":"First named in the newer half of the period's runs."}},"additionalProperties":false,"type":"object","required":["name","category","is_own_brand","mentions","platforms","is_new"],"title":"DataStudioCompetitor","description":"The brand or one competitor over the period, as the PDF report's share of voice lists them."},"DataStudioCompetitorList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/DataStudioCompetitor"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"True when more items exist past this page. Fetch them with a larger `offset`."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of items matching the query, across all pages."},"limit":{"type":"integer","minimum":1.0,"title":"Limit","description":"Page size that was applied."},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of items skipped before this page."}},"additionalProperties":false,"type":"object","required":["data","has_more","total","limit","offset"],"title":"DataStudioCompetitorList","description":"A page of the brand then its competitors, most mentioned first.","example":{"data":[{"category":"direct_competitor","change":1.8,"is_new":false,"is_own_brand":false,"mentions":64,"name":"Nike","platforms":"chatgpt, gemini, perplexity","share":21.3,"website":"https://www.nike.com"}],"has_more":false,"limit":500,"object":"list","offset":0,"total":1}},"DataStudioField":{"properties":{"name":{"type":"string","title":"Name","description":"The key of the column in each row."},"label":{"type":"string","title":"Label","description":"The name Data Studio shows."},"type":{"type":"string","enum":["text","number","boolean","date","url"],"title":"Type","description":"`text`, `number`, `boolean`, `date` (`YYYY-MM-DD`) or `url`; a score is a number from 0 to 100."},"concept":{"type":"string","enum":["dimension","metric"],"title":"Concept","description":"How Data Studio treats the column."},"aggregation":{"type":"string","enum":["sum","avg","max","none"],"title":"Aggregation","description":"The default aggregation of a metric; `none` for a dimension."},"description":{"type":"string","title":"Description","description":"What the column holds."}},"additionalProperties":false,"type":"object","required":["name","label","type","concept","aggregation","description"],"title":"DataStudioField","description":"One column of a source, as the connector declares it to Data Studio."},"DataStudioPrompt":{"properties":{"prompt":{"type":"string","title":"Prompt","description":"The prompt asked."},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category","description":"The prompt's current category."},"engine":{"type":"string","title":"Engine","description":"The AI platform that answered, e.g. `chatgpt`."},"appeared":{"type":"integer","minimum":0.0,"title":"Appeared","description":"Answers on this engine that named the brand."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Answers this engine gave to the prompt in the period."},"share":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Share","description":"`appeared` over `total`, in percent; null without answers."},"average_rank":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Rank","description":"The brand's mean position in the answers that named it; null when none did."}},"additionalProperties":false,"type":"object","required":["prompt","engine","appeared","total"],"title":"DataStudioPrompt","description":"One prompt on one engine over the period, as the PDF report's position by engine counts it."},"DataStudioPromptList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/DataStudioPrompt"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"True when more items exist past this page. Fetch them with a larger `offset`."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of items matching the query, across all pages."},"limit":{"type":"integer","minimum":1.0,"title":"Limit","description":"Page size that was applied."},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of items skipped before this page."}},"additionalProperties":false,"type":"object","required":["data","has_more","total","limit","offset"],"title":"DataStudioPromptList","description":"The engines of a page of prompts; `limit`, `offset` and `total` count prompts, not rows.","example":{"data":[{"appeared":8,"average_rank":2.1,"category":"Product","engine":"chatgpt","prompt":"best running shoes for flat feet","share":66.67,"total":12}],"has_more":false,"limit":500,"object":"list","offset":0,"total":1}},"DataStudioReport":{"properties":{"date":{"type":"string","format":"date","title":"Date","description":"Day the report ran (UTC)."},"report_id":{"type":"string","title":"Report Id","description":"The report's id."},"report_name":{"type":"string","title":"Report Name","description":"The report's name."},"location":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location","description":"Its city, else its country."},"score":{"type":"number","title":"Score","description":"Share of answers that named the brand, 0 to 100."},"ranked":{"type":"integer","minimum":0.0,"title":"Ranked","description":"Prompts with at least one answer naming the brand."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Prompts asked."},"answers":{"type":"integer","minimum":0.0,"title":"Answers","description":"Answers the engines gave."},"engines":{"type":"string","title":"Engines","description":"The AI platforms asked, comma separated."}},"additionalProperties":false,"type":"object","required":["date","report_id","report_name","score","ranked","total","answers","engines"],"title":"DataStudioReport","description":"One completed report: one run in one market, as the PDF report's run history lists it."},"DataStudioReportList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/DataStudioReport"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Opaque continuation token. Pass back as `?cursor=` to fetch the next page. `null` when `has_more` is false."}},"additionalProperties":false,"type":"object","required":["data","has_more"],"title":"DataStudioReportList","description":"A page of reports, newest first.","example":{"data":[{"answers":120,"date":"2026-10-27","engines":"chatgpt, perplexity, gemini, google_ai_mode, claude, copilot","location":"United States","ranked":17,"report_id":"c4f8b6a2-9a17-4e31-92fa-7d1e3b5c8b2a","report_name":"Running shoes, United States","score":42.5,"total":20}],"has_more":true,"next_cursor":"eyJ2IjoxLCJjIjoiMjAyNi0xMC0yN1QwODowMDowMCswMDowMCIsImkiOiJjNGY4In0","object":"list"}},"DataStudioSource":{"properties":{"object":{"type":"string","const":"data_studio_source","title":"Object","default":"data_studio_source"},"id":{"type":"string","enum":["brands","reports","prompts","citations","competitors","weekly-moves"],"title":"Id","description":"The source's id, the last segment of its path."},"label":{"type":"string","title":"Label","description":"Its name in the connector's picker."},"description":{"type":"string","title":"Description","description":"What one row is."},"path":{"type":"string","title":"Path","description":"The endpoint that serves its rows."},"per_brand":{"type":"boolean","title":"Per Brand","description":"True when the endpoint takes a `brand_id`."},"scope":{"type":"string","title":"Scope","description":"The scope a key needs to read it."},"pagination":{"type":"string","enum":["cursor","offset"],"title":"Pagination","description":"How its pages chain: `next_cursor` or `offset`."},"fields":{"items":{"$ref":"#/components/schemas/DataStudioField"},"type":"array","title":"Fields","description":"Its columns, in order."}},"additionalProperties":false,"type":"object","required":["id","label","description","path","per_brand","scope","pagination","fields"],"title":"DataStudioSource","description":"One source the connector offers, with its path and columns."},"DataStudioSourceList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/DataStudioSource"},"type":"array","title":"Data"}},"additionalProperties":false,"type":"object","required":["data"],"title":"DataStudioSourceList","description":"Every source the connector offers.","example":{"data":[{"description":"One row per completed report of the brand in the period.","fields":[{"aggregation":"avg","concept":"metric","description":"Share of answers that named the brand, 0 to 100.","label":"Visibility score","name":"score","type":"number"}],"id":"reports","label":"Reports with score","object":"data_studio_source","pagination":"cursor","path":"/v1/data-studio/reports","per_brand":true,"scope":"read:reports"}],"object":"list"}},"DataStudioWeeklyMove":{"properties":{"week":{"type":"string","title":"Week","description":"The ISO week, e.g. `2026-W43`."},"date":{"type":"string","format":"date","title":"Date","description":"Day of the week's newest run in its place (UTC)."},"report_id":{"type":"string","title":"Report Id","description":"That run's report."},"place":{"type":"string","title":"Place","description":"Its city, else its country."},"score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Score","description":"Its visibility score, 0 to 100."},"average":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average","description":"Mean score of the comparable runs in the four weeks before it."},"movement":{"anyOf":[{"type":"string","enum":["up","down","steady"]},{"type":"null"}],"title":"Movement","description":"Whether the score left the band a rerun would land in."},"band_low":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Band Low","description":"Low end of that band."},"band_high":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Band High","description":"High end of that band."},"kind":{"type":"string","enum":["score","won","lost","cited_new","cited_lost","competitor"],"title":"Kind","description":"`score` (one per run), `won` and `lost` (a prompt that started or stopped naming the brand on an engine), `cited_new` and `cited_lost` (a domain only one of the two runs cited) or `competitor`."},"prompt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prompt","description":"The prompt, on `won` and `lost`."},"platform":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Platform","description":"The AI platform, on `won` and `lost`."},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain","description":"The domain, on `cited_new` and `cited_lost`."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"A page of it that was cited, on `cited_new` and `cited_lost`."},"answers":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Answers","description":"Answers that cited it, on `cited_new` and `cited_lost`."},"competitor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Competitor","description":"The competitor, on `competitor`."},"before":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Before","description":"Its share of answers in the run before, on `competitor`."},"now":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Now","description":"Its share of answers in this run, on `competitor`."},"change":{"anyOf":[{"type":"string","enum":["entered","left","up","down"]},{"type":"null"}],"title":"Change","description":"How the competitor moved, on `competitor`."}},"additionalProperties":false,"type":"object","required":["week","date","report_id","place","kind"],"title":"DataStudioWeeklyMove","description":"One line of a week's moves, as the weekly digest says them: the score, then each prompt, domain or competitor."},"DataStudioWeeklyMoveList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/DataStudioWeeklyMove"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"True when more items exist past this page. Fetch them with a larger `offset`."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of items matching the query, across all pages."},"limit":{"type":"integer","minimum":1.0,"title":"Limit","description":"Page size that was applied."},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of items skipped before this page."}},"additionalProperties":false,"type":"object","required":["data","has_more","total","limit","offset"],"title":"DataStudioWeeklyMoveList","description":"The moves of a page of weeks; `limit`, `offset` and `total` count runs, not rows.","example":{"data":[{"average":38.1,"band_high":41.0,"band_low":36.0,"before":30.0,"change":"up","competitor":"Nike","date":"2026-10-27","kind":"competitor","movement":"up","now":41.7,"place":"United States","report_id":"c4f8b6a2-9a17-4e31-92fa-7d1e3b5c8b2a","score":42.5,"week":"2026-W43"}],"has_more":false,"limit":10,"object":"list","offset":0,"total":1}},"DirectoryCheck":{"properties":{"object":{"type":"string","const":"directory_check","title":"Object","description":"Always `directory_check`.","default":"directory_check"},"id":{"type":"string","title":"Id"},"status":{"type":"string","enum":["queued","running","completed","failed"],"title":"Status","description":"`queued`, `running`, `completed` or `failed` (one left running too long reads as failed)."},"directories":{"items":{"type":"string"},"type":"array","title":"Directories","description":"The directories it searches."},"credits":{"type":"integer","title":"Credits","description":"Credits reserved; what the searches that did not answer added is refunded."},"created_at":{"type":"string","format":"date-time","title":"Created At"},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Completed At"},"error":{"anyOf":[{"type":"string","enum":["no_search_answered","not_reserved","not_queued","stale","failed"]},{"type":"null"}],"title":"Error","description":"Why a failed check failed: `no_search_answered` (no directory search answered), `not_reserved` or `not_queued` (it could not start), `stale` (it ran too long) or `failed`. Null unless `status` is `failed`."}},"additionalProperties":false,"type":"object","required":["id","status","directories","credits","created_at"],"title":"DirectoryCheck","description":"A paid search of a place's directories."},"DirectoryCheckCreate":{"properties":{"directories":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":60},{"type":"null"}],"title":"Directories","description":"Only these directories (domains from the listings), searched again even if checked this week. Omitted: every searchable one not checked in the last week."}},"additionalProperties":false,"type":"object","title":"DirectoryCheckCreate","description":"Body for ``POST /v1/brands/{brand_id}/locations/{location_id}/directory-checks``.","example":{"directories":["yelp.com"]}},"DirectoryCheckQueued":{"properties":{"object":{"type":"string","const":"directory_check_request","title":"Object","description":"Always `directory_check_request`.","default":"directory_check_request"},"check":{"anyOf":[{"$ref":"#/components/schemas/DirectoryCheck"},{"type":"null"}],"description":"The check queued, or the latest one when there was nothing to search."},"searched":{"type":"integer","title":"Searched","description":"Directories it searches (0: nothing to search, nothing charged)."},"credits_charged":{"type":"integer","title":"Credits Charged","description":"Credits reserved for it."}},"additionalProperties":false,"type":"object","required":["searched","credits_charged"],"title":"DirectoryCheckQueued","description":"What a check request queued."},"DirectoryListing":{"properties":{"object":{"type":"string","const":"directory_listing","title":"Object","description":"Always `directory_listing`.","default":"directory_listing"},"directory":{"type":"string","title":"Directory","description":"The directory's domain, e.g. `yelp.com`."},"name":{"type":"string","title":"Name","description":"The directory's name."},"categories":{"items":{"type":"string","enum":["general","legal","health","home","hospitality"]},"type":"array","title":"Categories","description":"The kinds of business it lists."},"engine_sources":{"items":{"type":"string","enum":["chatgpt","claude","ai_overviews","grok","perplexity","gemini","muse"]},"type":"array","title":"Engine Sources","description":"AI platforms known to read it as a source of business data."},"signup_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signup Url","description":"Where a business claims or creates its listing."},"searchable":{"type":"boolean","title":"Searchable","description":"False when no check can search it; citations or the app's users say."},"citations":{"type":"integer","title":"Citations","description":"Times the brand's AI answers cited a page on this directory."},"status":{"type":"string","enum":["listed","missing","unknown"],"title":"Status","description":"`listed`, `missing` or `unknown` (never checked)."},"listing_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Listing Url","description":"The place's listing, when `listed`."},"found_by":{"anyOf":[{"type":"string","enum":["citation","business_data","search","manual"]},{"type":"null"}],"title":"Found By","description":"`citation` (an AI answer cited the listing), `business_data` (a Tripadvisor search), `search` (a Google site: search) or `manual` (set in the app; checks leave it alone)."},"match_signals":{"items":{"type":"string"},"type":"array","title":"Match Signals","description":"What tied the listing to the place: name, city, phone, address."},"checked_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Checked At","description":"When a check or a user last set the status."}},"additionalProperties":false,"type":"object","required":["directory","name","categories","engine_sources","searchable","citations","status","match_signals"],"title":"DirectoryListing","description":"One directory the place should be on, and whether it is listed there."},"DiscoveredPrompt":{"properties":{"object":{"type":"string","const":"discovered_prompt","title":"Object","description":"Always `discovered_prompt`.","default":"discovered_prompt"},"text":{"type":"string","title":"Text","description":"The question or keyword, as the source spells it."},"kind":{"type":"string","enum":["keyword","question"],"title":"Kind","description":"`keyword` for a search (Google demand, Search Console, ranking, research, fan-outs, Copilot), `question` for a prompt."},"source":{"type":"string","enum":["google_demand","search_console","ranking","research","page","competitors","fanouts","copilot"],"title":"Source","description":"Where it came from."},"volume":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Volume","description":"Monthly Google searches in the brand's market, when known."},"difficulty":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Difficulty","description":"Google keyword difficulty, 0 to 100, when known."},"intent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Intent","description":"Search intent (informational, commercial, ...), when known; `copilot`: Bing's."},"clicks":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Clicks","description":"`google_demand` and `search_console`: clicks in the last 28 days."},"impressions":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Impressions","description":"`google_demand` and `search_console`: impressions in the last 28 days."},"position":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Position","description":"`search_console` and `google_demand`: Search Console's average position; `ranking`: the ranked one."},"times":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Times","description":"`fanouts`: times the engines ran this search."},"prompts":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Prompts","description":"`fanouts`: prompts whose answers ran it."},"answers":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Answers","description":"`competitors`: answers to this prompt."},"brand_answers":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Brand Answers","description":"`competitors`: answers that name the brand."},"lost_answers":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Lost Answers","description":"`competitors`: answers that name a competitor and not the brand."},"competitors":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Competitors","description":"`competitors`: who won those answers, most answers first."},"platforms":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Platforms","description":"`competitors` and `fanouts`: the engines seen."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"`ranking` and `google_demand`: the page that ranks; `page`: the page read."},"origin":{"anyOf":[{"type":"string","enum":["gsc","ranked","both"]},{"type":"null"}],"title":"Origin","description":"`google_demand`: Search Console reports the query (`gsc`), the stored rankings hold it (`ranked`), or both."},"ctr":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ctr","description":"`google_demand`: clicks over impressions, as a fraction."},"ranked_position":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Ranked Position","description":"`google_demand`: the ranking page's position in the stored rankings."},"etv":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Etv","description":"`google_demand`: estimated monthly visits from the ranking, from the stored rankings."},"citations":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Citations","description":"`copilot`: times Copilot cited the brand's site in answers grounded on this query, per Bing."},"tracked_as_prompt":{"type":"boolean","title":"Tracked As Prompt","description":"The brand tracks this text as a prompt in a Scheduled Report."},"tracked_as_keyword":{"type":"boolean","title":"Tracked As Keyword","description":"The brand tracks this text as a Google keyword."}},"additionalProperties":false,"type":"object","required":["text","kind","source","tracked_as_prompt","tracked_as_keyword"],"title":"DiscoveredPrompt","description":"A question or keyword one source suggests tracking, with the numbers that source knows.","example":{"answers":12,"brand_answers":2,"competitors":["Nike","ASICS","Brooks"],"kind":"question","lost_answers":9,"object":"discovered_prompt","platforms":["chatgpt","gemini","perplexity"],"source":"competitors","text":"Which running shoe brands would you recommend for a first marathon?","tracked_as_keyword":false,"tracked_as_prompt":false}},"DiscoveredPromptList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/DiscoveredPrompt"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"True when more items exist past this page. Fetch them with a larger `offset`."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of items matching the query, across all pages."},"limit":{"type":"integer","minimum":1.0,"title":"Limit","description":"Page size that was applied."},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of items skipped before this page."},"credits_charged":{"type":"integer","minimum":0.0,"title":"Credits Charged","description":"Credits this call spent (0 for the free sources).","default":0},"cached":{"type":"boolean","title":"Cached","description":"A paid source answered from its cache, for nothing.","default":false},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Note","description":"Why a source has nothing yet and how to fill it."},"pending":{"type":"boolean","title":"Pending","description":"The source is still building its list for this brand: ask again in a minute.","default":false}},"additionalProperties":false,"type":"object","required":["data","has_more","total","limit","offset"],"title":"DiscoveredPromptList","description":"A page of discovered prompts from one source, with what the call cost.","example":{"cached":false,"credits_charged":0,"data":[{"answers":12,"brand_answers":2,"competitors":["Nike","ASICS","Brooks"],"kind":"question","lost_answers":9,"object":"discovered_prompt","platforms":["chatgpt","gemini","perplexity"],"source":"competitors","text":"Which running shoe brands would you recommend for a first marathon?","tracked_as_keyword":false,"tracked_as_prompt":false}],"has_more":false,"limit":25,"object":"list","offset":0,"pending":false,"total":1}},"DomainBucket":{"properties":{"keywords":{"type":"integer","title":"Keywords"},"top_3":{"type":"integer","title":"Top 3"},"top_10":{"type":"integer","title":"Top 10"},"top_20":{"type":"integer","title":"Top 20"},"estimated_traffic":{"type":"number","title":"Estimated Traffic"},"traffic_value":{"type":"number","title":"Traffic Value"},"new":{"type":"integer","title":"New"},"up":{"type":"integer","title":"Up"},"down":{"type":"integer","title":"Down"},"lost":{"type":"integer","title":"Lost"}},"type":"object","required":["keywords","top_3","top_10","top_20","estimated_traffic","traffic_value","new","up","down","lost"],"title":"DomainBucket"},"DomainEntry":{"properties":{"domain":{"type":"string","title":"Domain"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"overview":{"anyOf":[{"$ref":"#/components/schemas/DomainOverview"},{"type":"null"}]},"fetched_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Fetched At"}},"type":"object","required":["domain"],"title":"DomainEntry"},"DomainOverview":{"properties":{"domain":{"type":"string","title":"Domain"},"organic":{"$ref":"#/components/schemas/DomainBucket"},"paid":{"$ref":"#/components/schemas/DomainBucket"}},"type":"object","required":["domain","organic","paid"],"title":"DomainOverview"},"DomainRankingKeywords":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/RankedKeyword"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"True when more items exist past this page. Fetch them with a larger `offset`."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of items matching the query, across all pages."},"limit":{"type":"integer","minimum":1.0,"title":"Limit","description":"Page size that was applied."},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of items skipped before this page."},"domain":{"type":"string","title":"Domain"},"cached":{"type":"boolean","title":"Cached","description":"False when this site's rankings were never loaded: a competitor's overview is bought without them. `POST .../ranking-keywords/refreshes` loads them."},"stale":{"type":"boolean","title":"Stale","description":"Older than a week.","default":false},"fetched_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Fetched At","description":"When the rankings were loaded."},"load_credits":{"type":"integer","title":"Load Credits","description":"What `POST .../ranking-keywords/refreshes` charges now: 1 when never loaded or a week old, else 0.","default":0},"credits_charged":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Credits Charged","description":"Only on a refresh."}},"additionalProperties":false,"type":"object","required":["data","has_more","total","limit","offset","domain","cached"],"title":"DomainRankingKeywords","description":"A page of the keywords a site ranks for in Google's top 100, best positions first, from the weekly cache."},"Email":{"properties":{"object":{"type":"string","const":"email","title":"Object","default":"email"},"id":{"type":"string","title":"Id","description":"Email id."},"brand_id":{"type":"string","title":"Brand Id","description":"Owning brand id."},"status":{"type":"string","enum":["draft","scheduled","sent","opened","replied","bounced","failed","unsubscribed"],"title":"Status","description":"`draft`, `scheduled` (queued to go out), `sent`, `opened`, `replied`, `bounced`, `failed` or `unsubscribed`."},"recipient_email":{"type":"string","title":"Recipient Email","description":"Recipient."},"recipient_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Recipient Name","description":"The recipient's name."},"subject":{"type":"string","title":"Subject","description":"Subject."},"body":{"type":"string","title":"Body","description":"HTML body."},"body_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Body Text","description":"Plain-text body."},"mailbox_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mailbox Id","description":"The mailbox it goes out from."},"campaign_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Campaign Id","description":"The campaign that created it."},"contact_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contact Id","description":"The contact it goes to."},"citation_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Citation Url","description":"The cited page the pitch is about."},"citation_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Citation Id","description":"That page's id, when it is in Backlink outreach."},"template_type":{"anyOf":[{"type":"string","enum":["request_backlink","request_inclusion","build_relationship","follow_up","pitch"]},{"type":"null"}],"title":"Template Type","description":"What the email asks for."},"tone":{"type":"string","enum":["professional","casual","friendly","formal"],"title":"Tone","description":"`professional`, `casual`, `friendly` or `formal`."},"parent_email_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Email Id","description":"The thread's first email, for a follow-up or reply."},"follow_up_number":{"type":"integer","minimum":0.0,"title":"Follow Up Number","description":"0 for the first email of a thread, then 1, 2..."},"scheduled_for":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Scheduled For","description":"When a queued email goes out."},"sent_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Sent At","description":"When it went out."},"opened_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Opened At","description":"When it was first opened."},"replied_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Replied At","description":"When it got a reply."},"bounced_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Bounced At","description":"When it bounced."},"backlink_verified":{"type":"boolean","title":"Backlink Verified","description":"Whether the pitched page now links to the brand."},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message","description":"Why a `failed` email did not go out."},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Created At","description":"When it was created."},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Updated At","description":"Last change."}},"additionalProperties":false,"type":"object","required":["id","brand_id","status","recipient_email","subject","body","tone","follow_up_number","backlink_verified"],"title":"Email","description":"An outreach email: a draft, one queued to go out, or one sent and what it got.","example":{"backlink_verified":false,"body":"<p>Hi Alex, the adidas Adizero Boston 12 fits your list.</p>","body_text":"Hi Alex, the adidas Adizero Boston 12 fits your list.","brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","citation_id":"3c1f5a7e-8b2d-4e6f-9a0b-1c2d3e4f5a6b","citation_url":"https://www.runnersworld.com/gear/a20865766/best-running-shoes/","contact_id":"7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d","created_at":"2026-10-01T10:00:00+00:00","follow_up_number":0,"id":"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d","mailbox_id":"5e6f7081-92a3-4b4c-8d5e-6f708192a3b4","object":"email","recipient_email":"alex.rivera@e2e.test","recipient_name":"Alex Rivera","status":"draft","subject":"A shoe for your best running shoes list","template_type":"request_inclusion","tone":"friendly","updated_at":"2026-10-01T10:00:00+00:00"}},"EmailComposition":{"properties":{"recipient_email":{"type":"string","maxLength":255,"minLength":1,"title":"Recipient Email","description":"Recipient."},"recipient_name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Recipient Name","description":"The recipient's name."},"citation_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Citation Url","description":"The cited page the pitch is about; what was learned about it shapes the email."},"template_type":{"type":"string","enum":["request_backlink","request_inclusion","build_relationship","follow_up","pitch"],"title":"Template Type","description":"`request_backlink` (default), `request_inclusion`, `build_relationship`, `follow_up` or `pitch`.","default":"request_backlink"},"tone":{"type":"string","enum":["professional","casual","friendly","formal"],"title":"Tone","description":"`professional` (default), `casual`, `friendly` or `formal`.","default":"professional"},"custom_instructions":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Custom Instructions","description":"What to say or stress."},"mailbox_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mailbox Id","description":"The mailbox it should go out from."}},"additionalProperties":false,"type":"object","required":["recipient_email"],"title":"EmailComposition","description":"What an AI-written pitch is about.","example":{"citation_url":"https://www.runnersworld.com/gear/a20865766/best-running-shoes/","custom_instructions":"Mention the Adizero Boston 12's Lightstrike Pro cushioning.","recipient_email":"alex.rivera@e2e.test","recipient_name":"Alex Rivera","template_type":"request_inclusion","tone":"friendly"}},"EmailCreate":{"properties":{"recipient_email":{"type":"string","maxLength":255,"minLength":1,"title":"Recipient Email","description":"Recipient."},"recipient_name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Recipient Name","description":"The recipient's name."},"subject":{"type":"string","maxLength":500,"minLength":1,"title":"Subject","description":"Subject."},"body":{"type":"string","maxLength":100000,"minLength":1,"title":"Body","description":"HTML body."},"body_text":{"anyOf":[{"type":"string","maxLength":100000},{"type":"null"}],"title":"Body Text","description":"Plain-text body; derived from `body` when omitted."},"citation_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Citation Url","description":"The cited page the pitch is about."},"mailbox_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mailbox Id","description":"The mailbox it should go out from."},"template_type":{"anyOf":[{"type":"string","enum":["request_backlink","request_inclusion","build_relationship","follow_up","pitch"]},{"type":"null"}],"title":"Template Type","description":"What the email asks for."},"tone":{"type":"string","enum":["professional","casual","friendly","formal"],"title":"Tone","description":"`professional` (default), `casual`, `friendly` or `formal`.","default":"professional"}},"additionalProperties":false,"type":"object","required":["recipient_email","subject","body"],"title":"EmailCreate","description":"A draft written by hand; nothing is sent until `POST .../emails/{email_id}/sends`.","example":{"body":"<p>Hi Alex, the adidas Adizero Boston 12 fits your list.</p>","citation_url":"https://www.runnersworld.com/gear/a20865766/best-running-shoes/","mailbox_id":"5e6f7081-92a3-4b4c-8d5e-6f708192a3b4","recipient_email":"alex.rivera@e2e.test","recipient_name":"Alex Rivera","subject":"A shoe for your best running shoes list"}},"EmailList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/Email"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Opaque continuation token. Pass back as `?cursor=` to fetch the next page. `null` when `has_more` is false."}},"additionalProperties":false,"type":"object","required":["data","has_more"],"title":"EmailList","description":"A page of emails, newest first.","example":{"data":[{"backlink_verified":false,"body":"<p>Hi Alex, the adidas Adizero Boston 12 fits your list.</p>","body_text":"Hi Alex, the adidas Adizero Boston 12 fits your list.","brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","citation_id":"3c1f5a7e-8b2d-4e6f-9a0b-1c2d3e4f5a6b","citation_url":"https://www.runnersworld.com/gear/a20865766/best-running-shoes/","contact_id":"7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d","created_at":"2026-10-01T10:00:00+00:00","follow_up_number":0,"id":"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d","mailbox_id":"5e6f7081-92a3-4b4c-8d5e-6f708192a3b4","object":"email","recipient_email":"alex.rivera@e2e.test","recipient_name":"Alex Rivera","status":"draft","subject":"A shoe for your best running shoes list","template_type":"request_inclusion","tone":"friendly","updated_at":"2026-10-01T10:00:00+00:00"}],"has_more":false,"object":"list"}},"EmailReply":{"properties":{"object":{"type":"string","const":"email_reply","title":"Object","default":"email_reply"},"id":{"type":"string","title":"Id","description":"Reply id."},"email_id":{"type":"string","title":"Email Id","description":"The email it answers; `GET .../emails/{email_id}/thread` reads the thread."},"from_email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"From Email","description":"Sender."},"from_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"From Name","description":"The sender's name."},"subject":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subject","description":"Subject."},"snippet":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Snippet","description":"The start of its text."},"received_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Received At","description":"When it arrived."},"is_read":{"type":"boolean","title":"Is Read","description":"Whether someone read it in the app."},"recipient_email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Recipient Email","description":"Who the answered email went to."},"citation_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Citation Url","description":"The cited page the answered email pitched."}},"additionalProperties":false,"type":"object","required":["id","email_id","is_read"],"title":"EmailReply","description":"A reply the brand's outreach got.","example":{"citation_url":"https://www.runnersworld.com/gear/a20865766/best-running-shoes/","email_id":"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d","from_email":"alex.rivera@e2e.test","from_name":"Alex Rivera","id":"b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e","is_read":false,"object":"email_reply","received_at":"2026-10-02T14:00:00+00:00","recipient_email":"alex.rivera@e2e.test","snippet":"Sounds good, send me a pair to test.","subject":"Re: A shoe for your best running shoes list"}},"EmailReplyDraftCreate":{"properties":{"body":{"type":"string","maxLength":50000,"minLength":1,"title":"Body","description":"The reply as plain text; line breaks are kept."}},"additionalProperties":false,"type":"object","required":["body"],"title":"EmailReplyDraftCreate","description":"A reply to write in an email's thread.","example":{"body":"Thanks Alex! Here is the product page."}},"EmailReplyList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/EmailReply"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Opaque continuation token. Pass back as `?cursor=` to fetch the next page. `null` when `has_more` is false."}},"additionalProperties":false,"type":"object","required":["data","has_more"],"title":"EmailReplyList","description":"A page of replies, newest first."},"EmailSend":{"properties":{"mailbox_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mailbox Id","description":"The mailbox; omitted, the one the email was saved with, else the default, else the only one."},"send_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Send At","description":"When to send (ISO 8601); omitted, now."}},"additionalProperties":false,"type":"object","title":"EmailSend","description":"Where and when a draft goes out.","example":{"mailbox_id":"5e6f7081-92a3-4b4c-8d5e-6f708192a3b4"}},"EmailSequence":{"properties":{"object":{"type":"string","const":"email_sequence","title":"Object","default":"email_sequence"},"id":{"type":"string","title":"Id","description":"Sequence id."},"brand_id":{"type":"string","title":"Brand Id","description":"Owning brand id."},"name":{"type":"string","title":"Name","description":"Name."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Description."},"steps":{"items":{"$ref":"#/components/schemas/SequenceStep"},"type":"array","title":"Steps","description":"The steps, as a graph."},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Created At","description":"When the sequence was created."},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Updated At","description":"Last change."}},"additionalProperties":false,"type":"object","required":["id","brand_id","name"],"title":"EmailSequence","description":"A multi-step sequence: emails, waits, and follow-ups that branch on opens or replies.","example":{"brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","created_at":"2026-09-20T10:00:00+00:00","id":"4d5e6f70-8192-4a3b-9c4d-5e6f7a8b9c0d","name":"Pitch and one follow-up","object":"email_sequence","steps":[{"id":"s1","next_step_id":"s2","order":0,"template_id":"2b3c4d5e-6f70-4a1b-8c2d-3e4f5a6b7c8d","type":"email"},{"id":"s2","next_step_id":"s3","order":1,"type":"wait","wait_days":3},{"condition_timeout_days":0,"condition_type":"replied","id":"s3","on_false_step_id":"s4","order":2,"type":"condition"},{"id":"s4","order":3,"subject_override":"Following up","template_id":"2b3c4d5e-6f70-4a1b-8c2d-3e4f5a6b7c8d","type":"email"}],"updated_at":"2026-09-20T10:00:00+00:00"}},"EmailSequenceCreate":{"properties":{"name":{"type":"string","maxLength":200,"minLength":1,"title":"Name","description":"Name."},"description":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Description","description":"Description."},"steps":{"items":{"$ref":"#/components/schemas/SequenceStep"},"type":"array","maxItems":50,"minItems":1,"title":"Steps","description":"The steps (1 to 50)."}},"additionalProperties":false,"type":"object","required":["name","steps"],"title":"EmailSequenceCreate","description":"A new sequence.","example":{"name":"Pitch and one follow-up","steps":[{"id":"s1","next_step_id":"s2","order":0,"template_id":"2b3c4d5e-6f70-4a1b-8c2d-3e4f5a6b7c8d","type":"email"},{"id":"s2","next_step_id":"s3","order":1,"type":"wait","wait_days":3},{"condition_timeout_days":0,"condition_type":"replied","id":"s3","on_false_step_id":"s4","order":2,"type":"condition"},{"id":"s4","order":3,"subject_override":"Following up","template_id":"2b3c4d5e-6f70-4a1b-8c2d-3e4f5a6b7c8d","type":"email"}]}},"EmailSequenceDetail":{"properties":{"object":{"type":"string","const":"email_sequence","title":"Object","default":"email_sequence"},"id":{"type":"string","title":"Id","description":"Sequence id."},"brand_id":{"type":"string","title":"Brand Id","description":"Owning brand id."},"name":{"type":"string","title":"Name","description":"Name."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Description."},"steps":{"items":{"$ref":"#/components/schemas/SequenceStep"},"type":"array","title":"Steps","description":"The steps, as a graph."},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Created At","description":"When the sequence was created."},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Updated At","description":"Last change."},"template_names":{"additionalProperties":{"type":"string"},"type":"object","title":"Template Names","description":"Template names by template id."},"results":{"$ref":"#/components/schemas/SequenceResults"}},"additionalProperties":false,"type":"object","required":["id","brand_id","name","results"],"title":"EmailSequenceDetail","description":"A sequence with its templates' names and how each step performs.","example":{"brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","created_at":"2026-09-20T10:00:00+00:00","id":"4d5e6f70-8192-4a3b-9c4d-5e6f7a8b9c0d","name":"Pitch and one follow-up","object":"email_sequence","results":{"conversion_rate":0.0,"steps":[],"total_emails":0,"total_replied":0},"steps":[{"id":"s1","next_step_id":"s2","order":0,"template_id":"2b3c4d5e-6f70-4a1b-8c2d-3e4f5a6b7c8d","type":"email"},{"id":"s2","next_step_id":"s3","order":1,"type":"wait","wait_days":3},{"condition_timeout_days":0,"condition_type":"replied","id":"s3","on_false_step_id":"s4","order":2,"type":"condition"},{"id":"s4","order":3,"subject_override":"Following up","template_id":"2b3c4d5e-6f70-4a1b-8c2d-3e4f5a6b7c8d","type":"email"}],"template_names":{"2b3c4d5e-6f70-4a1b-8c2d-3e4f5a6b7c8d":"Best running shoes pitch"},"updated_at":"2026-09-20T10:00:00+00:00"}},"EmailSequenceList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/EmailSequence"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Opaque continuation token. Pass back as `?cursor=` to fetch the next page. `null` when `has_more` is false."}},"additionalProperties":false,"type":"object","required":["data","has_more"],"title":"EmailSequenceList","description":"A page of sequences, newest first.","example":{"data":[{"brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","created_at":"2026-09-20T10:00:00+00:00","id":"4d5e6f70-8192-4a3b-9c4d-5e6f7a8b9c0d","name":"Pitch and one follow-up","object":"email_sequence","steps":[{"id":"s1","next_step_id":"s2","order":0,"template_id":"2b3c4d5e-6f70-4a1b-8c2d-3e4f5a6b7c8d","type":"email"},{"id":"s2","next_step_id":"s3","order":1,"type":"wait","wait_days":3},{"condition_timeout_days":0,"condition_type":"replied","id":"s3","on_false_step_id":"s4","order":2,"type":"condition"},{"id":"s4","order":3,"subject_override":"Following up","template_id":"2b3c4d5e-6f70-4a1b-8c2d-3e4f5a6b7c8d","type":"email"}],"updated_at":"2026-09-20T10:00:00+00:00"}],"has_more":false,"object":"list"}},"EmailSequenceUpdate":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":200,"minLength":1},{"type":"null"}],"title":"Name","description":"Name."},"description":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Description","description":"Description."},"steps":{"anyOf":[{"items":{"$ref":"#/components/schemas/SequenceStep"},"type":"array","maxItems":50},{"type":"null"}],"title":"Steps","description":"The full step list. A sequence an active campaign uses must stay complete."}},"additionalProperties":false,"type":"object","title":"EmailSequenceUpdate","description":"Changes to a sequence; `steps` replaces the whole graph.","example":{"name":"Pitch, wait, follow up"}},"EmailSummary":{"properties":{"object":{"type":"string","const":"email_summary","title":"Object","default":"email_summary"},"by_status":{"additionalProperties":{"type":"integer"},"type":"object","title":"By Status","description":"Emails per status: `draft`, `scheduled` (queued to go out), `sent`, `opened`, `replied`, `bounced`, `failed` or `unsubscribed`."},"total_sent":{"type":"integer","minimum":0.0,"title":"Total Sent","description":"Emails that went out (sent, opened, replied or unsubscribed)."},"total_opened":{"type":"integer","minimum":0.0,"title":"Total Opened","description":"Of those, opened."},"open_rate":{"type":"number","title":"Open Rate","description":"Opened over sent, in percent."},"reply_rate":{"type":"number","title":"Reply Rate","description":"Replied over sent, in percent."},"bounce_rate":{"type":"number","title":"Bounce Rate","description":"Bounced over sent, in percent."}},"additionalProperties":false,"type":"object","required":["by_status","total_sent","total_opened","open_rate","reply_rate","bounce_rate"],"title":"EmailSummary","description":"The brand's outreach emails counted by status, with lifetime rates.","example":{"bounce_rate":2.8,"by_status":{"bounced":1,"draft":3,"opened":12,"replied":4,"scheduled":5,"sent":20},"object":"email_summary","open_rate":44.4,"reply_rate":11.1,"total_opened":16,"total_sent":36}},"EmailTemplate":{"properties":{"object":{"type":"string","const":"email_template","title":"Object","default":"email_template"},"id":{"type":"string","title":"Id","description":"Template id."},"brand_id":{"type":"string","title":"Brand Id","description":"Owning brand id."},"name":{"type":"string","title":"Name","description":"Name."},"template_type":{"type":"string","enum":["request_backlink","request_inclusion","build_relationship","follow_up","pitch"],"title":"Template Type","description":"What the email asks for: `request_backlink`, `request_inclusion`, `build_relationship`, `follow_up` or `pitch`."},"subject":{"type":"string","title":"Subject","description":"Subject line. Placeholders filled per contact: `{{first_name}}`, `{{name}}`, `{{email}}`, `{{company}}`, `{{brand_name}}`, and from the cited page a contact was added with `{{page_url}}`, `{{page_title}}`, `{{role}}`."},"body":{"type":"string","title":"Body","description":"HTML body. Placeholders filled per contact: `{{first_name}}`, `{{name}}`, `{{email}}`, `{{company}}`, `{{brand_name}}`, and from the cited page a contact was added with `{{page_url}}`, `{{page_title}}`, `{{role}}`."},"body_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Body Text","description":"Plain-text body."},"variables":{"items":{"type":"string"},"type":"array","title":"Variables","description":"Placeholders the template uses."},"is_default":{"type":"boolean","title":"Is Default","description":"The default template of its type."},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Created At","description":"When the template was created."},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Updated At","description":"Last change."}},"additionalProperties":false,"type":"object","required":["id","brand_id","name","template_type","subject","body","is_default"],"title":"EmailTemplate","description":"An email a campaign or a sequence step sends.","example":{"body":"<p>Hi {{first_name}}, I read {{page_url}} and thought the adidas Adizero Boston 12 fits it.</p>","body_text":"Hi {{first_name}}, I read {{page_url}} and thought the adidas Adizero Boston 12 fits it.","brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","created_at":"2026-09-20T10:00:00+00:00","id":"2b3c4d5e-6f70-4a1b-8c2d-3e4f5a6b7c8d","is_default":false,"name":"Best running shoes pitch","object":"email_template","subject":"{{first_name}}, a shoe for {{page_title}}","template_type":"request_inclusion","updated_at":"2026-09-20T10:00:00+00:00","variables":["first_name","page_title","page_url"]}},"EmailTemplateCreate":{"properties":{"name":{"type":"string","maxLength":200,"minLength":1,"title":"Name","description":"Name."},"template_type":{"type":"string","enum":["request_backlink","request_inclusion","build_relationship","follow_up","pitch"],"title":"Template Type","description":"`request_backlink`, `request_inclusion`, `build_relationship`, `follow_up` or `pitch`."},"subject":{"type":"string","maxLength":500,"minLength":1,"title":"Subject","description":"Subject line. Placeholders filled per contact: `{{first_name}}`, `{{name}}`, `{{email}}`, `{{company}}`, `{{brand_name}}`, and from the cited page a contact was added with `{{page_url}}`, `{{page_title}}`, `{{role}}`."},"body":{"type":"string","maxLength":50000,"minLength":1,"title":"Body","description":"HTML body. Placeholders filled per contact: `{{first_name}}`, `{{name}}`, `{{email}}`, `{{company}}`, `{{brand_name}}`, and from the cited page a contact was added with `{{page_url}}`, `{{page_title}}`, `{{role}}`."},"body_text":{"anyOf":[{"type":"string","maxLength":50000},{"type":"null"}],"title":"Body Text","description":"Plain-text body."},"is_default":{"type":"boolean","title":"Is Default","description":"Make it the default template of its type.","default":false}},"additionalProperties":false,"type":"object","required":["name","template_type","subject","body"],"title":"EmailTemplateCreate","description":"A new email template.","example":{"body":"<p>Hi {{first_name}}, I read {{page_url}} and thought the adidas Adizero Boston 12 fits it.</p>","is_default":false,"name":"Best running shoes pitch","subject":"{{first_name}}, a shoe for {{page_title}}","template_type":"request_inclusion"}},"EmailTemplateList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/EmailTemplate"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Opaque continuation token. Pass back as `?cursor=` to fetch the next page. `null` when `has_more` is false."}},"additionalProperties":false,"type":"object","required":["data","has_more"],"title":"EmailTemplateList","description":"A page of templates, newest first.","example":{"data":[{"body":"<p>Hi {{first_name}}, I read {{page_url}} and thought the adidas Adizero Boston 12 fits it.</p>","body_text":"Hi {{first_name}}, I read {{page_url}} and thought the adidas Adizero Boston 12 fits it.","brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","created_at":"2026-09-20T10:00:00+00:00","id":"2b3c4d5e-6f70-4a1b-8c2d-3e4f5a6b7c8d","is_default":false,"name":"Best running shoes pitch","object":"email_template","subject":"{{first_name}}, a shoe for {{page_title}}","template_type":"request_inclusion","updated_at":"2026-09-20T10:00:00+00:00","variables":["first_name","page_title","page_url"]}],"has_more":false,"object":"list"}},"EmailTemplateUpdate":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":200,"minLength":1},{"type":"null"}],"title":"Name","description":"Name."},"template_type":{"anyOf":[{"type":"string","enum":["request_backlink","request_inclusion","build_relationship","follow_up","pitch"]},{"type":"null"}],"title":"Template Type","description":"`request_backlink`, `request_inclusion`, `build_relationship`, `follow_up` or `pitch`."},"subject":{"anyOf":[{"type":"string","maxLength":500,"minLength":1},{"type":"null"}],"title":"Subject","description":"Subject line."},"body":{"anyOf":[{"type":"string","maxLength":50000,"minLength":1},{"type":"null"}],"title":"Body","description":"HTML body."},"body_text":{"anyOf":[{"type":"string","maxLength":50000},{"type":"null"}],"title":"Body Text","description":"Plain-text body."},"is_default":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Default","description":"`true` makes it the default template of its type."}},"additionalProperties":false,"type":"object","title":"EmailTemplateUpdate","description":"Changes to a template.","example":{"subject":"A shoe for your list"}},"EmailThread":{"properties":{"object":{"type":"string","const":"email_thread","title":"Object","default":"email_thread"},"emails":{"items":{"$ref":"#/components/schemas/Email"},"type":"array","title":"Emails","description":"The thread's emails."},"replies":{"items":{"$ref":"#/components/schemas/EmailThreadReply"},"type":"array","title":"Replies","description":"The replies to them."}},"additionalProperties":false,"type":"object","title":"EmailThread","description":"A whole conversation: every email sent in the thread and every reply, oldest first."},"EmailThreadReply":{"properties":{"id":{"type":"string","title":"Id","description":"Reply id."},"email_id":{"type":"string","title":"Email Id","description":"The email it answers."},"from_email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"From Email","description":"Sender."},"from_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"From Name","description":"The sender's name."},"subject":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subject","description":"Subject."},"body_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Body Text","description":"Plain-text body."},"received_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Received At","description":"When it arrived."},"is_read":{"type":"boolean","title":"Is Read","description":"Whether someone read it in the app."}},"additionalProperties":false,"type":"object","required":["id","email_id","is_read"],"title":"EmailThreadReply","description":"A reply in a thread, with its full text."},"EmailUpdate":{"properties":{"recipient_email":{"anyOf":[{"type":"string","maxLength":255,"minLength":1},{"type":"null"}],"title":"Recipient Email","description":"Recipient."},"recipient_name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Recipient Name","description":"The recipient's name."},"subject":{"anyOf":[{"type":"string","maxLength":500,"minLength":1},{"type":"null"}],"title":"Subject","description":"Subject."},"body":{"anyOf":[{"type":"string","maxLength":100000,"minLength":1},{"type":"null"}],"title":"Body","description":"HTML body; the plain-text body follows it."},"mailbox_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mailbox Id","description":"The mailbox it goes out from."}},"additionalProperties":false,"type":"object","title":"EmailUpdate","description":"Changes to a draft or a queued email.","example":{"subject":"A shoe for your list"}},"EmailVariant":{"properties":{"object":{"type":"string","const":"email_variant","title":"Object","default":"email_variant"},"id":{"type":"string","title":"Id","description":"Variant id."},"sequence_id":{"type":"string","title":"Sequence Id","description":"The sequence."},"step_id":{"type":"string","title":"Step Id","description":"The email step it varies."},"variant_name":{"type":"string","title":"Variant Name","description":"Name, e.g. `B`."},"template_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Template Id","description":"The template it sends."},"subject_override":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subject Override","description":"Its own subject."},"body_override":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Body Override","description":"Its own HTML body."},"traffic_percentage":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Traffic Percentage","description":"Share of the step's contacts it gets, in percent."},"is_winner":{"type":"boolean","title":"Is Winner","description":"Declared the winner: it now gets all of the step's contacts."},"winner_declared_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Winner Declared At","description":"When it was declared the winner."},"results":{"anyOf":[{"$ref":"#/components/schemas/EmailVariantResults"},{"type":"null"}],"description":"How it performs; on the list only, `null` on a write."},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Created At","description":"When the variant was created."},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Updated At","description":"Last change."}},"additionalProperties":false,"type":"object","required":["id","sequence_id","step_id","variant_name","traffic_percentage","is_winner"],"title":"EmailVariant","description":"An A/B variant of one email step: another template, subject or body, sent to a share of the contacts.","example":{"created_at":"2026-09-20T10:00:00+00:00","id":"6f708192-a3b4-4c5d-8e6f-7a8b9c0d1e2f","is_winner":false,"object":"email_variant","results":{"bounced":0,"open_rate":60.0,"opened":6,"replied":2,"reply_rate":20.0,"sent":10},"sequence_id":"4d5e6f70-8192-4a3b-9c4d-5e6f7a8b9c0d","step_id":"s1","subject_override":"Quick question about {{page_title}}","template_id":"2b3c4d5e-6f70-4a1b-8c2d-3e4f5a6b7c8d","traffic_percentage":50,"updated_at":"2026-09-20T10:00:00+00:00","variant_name":"B"}},"EmailVariantCreate":{"properties":{"variant_name":{"type":"string","maxLength":100,"minLength":1,"title":"Variant Name","description":"Name, unique in the step."},"template_id":{"type":"string","title":"Template Id","description":"The template it sends: the step's own when only the subject changes."},"subject_override":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Subject Override","description":"Its own subject."},"body_override":{"anyOf":[{"type":"string","maxLength":100000},{"type":"null"}],"title":"Body Override","description":"Its own HTML body."},"traffic_percentage":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Traffic Percentage","description":"Share of the step's contacts, in percent; the step's variants sum to 100 at most.","default":50}},"additionalProperties":false,"type":"object","required":["variant_name","template_id"],"title":"EmailVariantCreate","description":"A new A/B variant for one email step.","example":{"subject_override":"Quick question about {{page_title}}","template_id":"2b3c4d5e-6f70-4a1b-8c2d-3e4f5a6b7c8d","traffic_percentage":50,"variant_name":"B"}},"EmailVariantList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/EmailVariant"},"type":"array","title":"Data"}},"additionalProperties":false,"type":"object","required":["data"],"title":"EmailVariantList","description":"A sequence's variants with their results, by step.","example":{"data":[{"created_at":"2026-09-20T10:00:00+00:00","id":"6f708192-a3b4-4c5d-8e6f-7a8b9c0d1e2f","is_winner":false,"object":"email_variant","results":{"bounced":0,"open_rate":60.0,"opened":6,"replied":2,"reply_rate":20.0,"sent":10},"sequence_id":"4d5e6f70-8192-4a3b-9c4d-5e6f7a8b9c0d","step_id":"s1","subject_override":"Quick question about {{page_title}}","template_id":"2b3c4d5e-6f70-4a1b-8c2d-3e4f5a6b7c8d","traffic_percentage":50,"updated_at":"2026-09-20T10:00:00+00:00","variant_name":"B"}],"object":"list"}},"EmailVariantResults":{"properties":{"sent":{"type":"integer","minimum":0.0,"title":"Sent","description":"Emails sent."},"opened":{"type":"integer","minimum":0.0,"title":"Opened","description":"Of those, opened."},"replied":{"type":"integer","minimum":0.0,"title":"Replied","description":"Of those, replied to."},"bounced":{"type":"integer","minimum":0.0,"title":"Bounced","description":"Of those, bounced."},"open_rate":{"type":"number","title":"Open Rate","description":"Opened over sent, in percent."},"reply_rate":{"type":"number","title":"Reply Rate","description":"Replied over sent, in percent."}},"additionalProperties":false,"type":"object","required":["sent","opened","replied","bounced","open_rate","reply_rate"],"title":"EmailVariantResults","description":"How a variant performs."},"EmailVariantUpdate":{"properties":{"variant_name":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Variant Name","description":"Name."},"template_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Template Id","description":"The template it sends."},"subject_override":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Subject Override","description":"Its own subject."},"body_override":{"anyOf":[{"type":"string","maxLength":100000},{"type":"null"}],"title":"Body Override","description":"Its own HTML body."},"traffic_percentage":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":1.0},{"type":"null"}],"title":"Traffic Percentage","description":"Share of the step's contacts."},"is_winner":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Winner","description":"`true` declares it the winner; the other fields are then ignored."}},"additionalProperties":false,"type":"object","title":"EmailVariantUpdate","description":"Changes to a variant, or the call that declares it the winner.","example":{"is_winner":true}},"Fanout":{"properties":{"object":{"type":"string","const":"fanout","title":"Object","description":"Always `fanout`.","default":"fanout"},"query":{"type":"string","title":"Query","description":"The search, lower case with whitespace collapsed; the grouping key."},"sample":{"type":"string","title":"Sample","description":"One spelling of the search exactly as an engine sent it, or the question as Google wrote it."},"times":{"type":"integer","minimum":0.0,"title":"Times","description":"Times the engines ran this search in the filtered window; 0 for a question only Google shows."},"prompt_count":{"type":"integer","minimum":0.0,"title":"Prompt Count","description":"Distinct prompts whose answers ran it."},"platforms":{"items":{"type":"string"},"type":"array","title":"Platforms","description":"Engines that ran it (an open set, e.g. `chatgpt`, `gemini`)."},"keywords":{"items":{"type":"string"},"type":"array","title":"Keywords","description":"The tracked keywords whose last Google page lists it under People also ask; empty for a search only the engines ran."},"first_seen_at":{"type":"string","format":"date-time","title":"First Seen At","description":"When an engine first ran it, or a rank check first saw the question."},"last_seen_at":{"type":"string","format":"date-time","title":"Last Seen At","description":"When an engine last ran it, or a rank check last saw the question."}},"additionalProperties":false,"type":"object","required":["query","sample","times","prompt_count","platforms","keywords","first_seen_at","last_seen_at"],"title":"Fanout","description":"A web search the engines ran while answering the brand's prompts, a People also ask question, or both.","example":{"first_seen_at":"2026-08-02T09:00:00+00:00","keywords":[],"last_seen_at":"2026-09-20T08:15:00+00:00","object":"fanout","platforms":["chatgpt","gemini"],"prompt_count":4,"query":"best marathon running shoes 2026","sample":"Best marathon running shoes 2026","times":9}},"FanoutList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/Fanout"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"True when more items exist past this page. Fetch them with a larger `offset`."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of items matching the query, across all pages."},"limit":{"type":"integer","minimum":1.0,"title":"Limit","description":"Page size that was applied."},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of items skipped before this page."}},"additionalProperties":false,"type":"object","required":["data","has_more","total","limit","offset"],"title":"FanoutList","description":"A page of fan-out searches in the order `sort` asks, most frequent first by default.","example":{"data":[{"first_seen_at":"2026-08-02T09:00:00+00:00","keywords":[],"last_seen_at":"2026-09-20T08:15:00+00:00","object":"fanout","platforms":["chatgpt","gemini"],"prompt_count":4,"query":"best marathon running shoes 2026","sample":"Best marathon running shoes 2026","times":9}],"has_more":false,"limit":100,"object":"list","offset":0,"total":1}},"FanoutPrompt":{"properties":{"object":{"type":"string","const":"fanout_prompt","title":"Object","description":"Always `fanout_prompt`.","default":"fanout_prompt"},"prompt_text":{"type":"string","title":"Prompt Text","description":"The prompt, as it was asked."},"platform":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Platform","description":"The engine that ran the search (an open set)."},"times":{"type":"integer","minimum":0.0,"title":"Times","description":"Answers of this prompt on this engine that ran the search."},"last_seen_at":{"type":"string","format":"date-time","title":"Last Seen At","description":"When the engine last ran it for this prompt."}},"additionalProperties":false,"type":"object","required":["prompt_text","times","last_seen_at"],"title":"FanoutPrompt","description":"A prompt whose answers made one engine run the search, and how often.","example":{"last_seen_at":"2026-09-20T08:15:00+00:00","object":"fanout_prompt","platform":"chatgpt","prompt_text":"Which burr grinder is best for espresso at home?","times":3}},"FanoutPromptList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/FanoutPrompt"},"type":"array","title":"Data"}},"additionalProperties":false,"type":"object","required":["data"],"title":"FanoutPromptList","description":"Every prompt behind one search, most frequent first.","example":{"data":[{"last_seen_at":"2026-09-20T08:15:00+00:00","object":"fanout_prompt","platform":"chatgpt","prompt_text":"Which burr grinder is best for espresso at home?","times":3}],"object":"list"}},"Ga4Property":{"properties":{"object":{"type":"string","const":"ga4_property","title":"Object","default":"ga4_property"},"property_id":{"type":"string","title":"Property Id","description":"Resource name, e.g. `properties/123456789`."},"display_name":{"type":"string","title":"Display Name"},"account_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Account Name"}},"additionalProperties":false,"type":"object","required":["property_id","display_name"],"title":"Ga4Property","description":"A GA4 property the connected Google account can read."},"GapCacheState":{"properties":{"missing":{"items":{"type":"string"},"type":"array","title":"Missing"},"stale":{"items":{"type":"string"},"type":"array","title":"Stale"}},"type":"object","required":["missing","stale"],"title":"GapCacheState"},"GapCompetitor":{"properties":{"domain":{"type":"string","title":"Domain"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"position":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Position"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"},"etv":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Etv"},"is_featured_snippet":{"type":"boolean","title":"Is Featured Snippet","default":false}},"type":"object","required":["domain"],"title":"GapCompetitor"},"GapCompetitorState":{"properties":{"domain":{"type":"string","title":"Domain"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"manual":{"type":"boolean","title":"Manual","description":"Added by hand, not found by the brand's reports.","default":false},"available":{"type":"boolean","title":"Available"},"stale":{"type":"boolean","title":"Stale"},"fetched_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Fetched At"},"keywords":{"type":"integer","title":"Keywords"}},"type":"object","required":["domain","available","stale","keywords"],"title":"GapCompetitorState"},"GbpAudit":{"properties":{"score":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Score"},"grade":{"type":"string","enum":["A","B","C","D","F"],"title":"Grade"},"field_statuses":{"items":{"$ref":"#/components/schemas/GbpFieldStatus"},"type":"array","title":"Field Statuses"}},"additionalProperties":false,"type":"object","required":["score","grade"],"title":"GbpAudit","description":"The profile's audit: the 0 to 100 score over the checks measured, and each measured check's state (`field_id` names the check)."},"GbpAuditCheck":{"properties":{"id":{"type":"string","title":"Id","description":"The check, such as `reviews.reply_rate`."},"section":{"type":"string","title":"Section"},"weight":{"type":"integer","maximum":3.0,"minimum":1.0,"title":"Weight","description":"Priority: 3 high, 2 medium, 1 low."},"status":{"type":"string","enum":["pass","warn","fail","not_measurable"],"title":"Status"},"reason":{"anyOf":[{"type":"string","enum":["needs_access","no_data","not_applicable","self_attest"]},{"type":"null"}],"title":"Reason"},"label":{"type":"string","title":"Label"},"finding":{"type":"string","title":"Finding","description":"What the run found, with the numbers, in the caller's language."},"value":{"additionalProperties":true,"type":"object","title":"Value"},"target":{"additionalProperties":true,"type":"object","title":"Target"},"fix":{"type":"string","enum":["apply","approve","draft","task","info"],"title":"Fix"}},"additionalProperties":false,"type":"object","required":["id","section","weight","status","label","finding","fix"],"title":"GbpAuditCheck","description":"One check of an audit run."},"GbpAuditRun":{"properties":{"object":{"type":"string","const":"gbp_audit","title":"Object","description":"Always `gbp_audit`.","default":"gbp_audit"},"id":{"type":"string","title":"Id"},"location_id":{"type":"string","title":"Location Id","description":"The linked location."},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Created At"},"score":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Score"},"measured":{"type":"integer","title":"Measured"},"total":{"type":"integer","title":"Total"},"counts":{"additionalProperties":{"type":"integer"},"type":"object","title":"Counts","description":"Checks per status: pass, warn, fail, not_measurable."},"previous_score":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Previous Score"},"checks":{"items":{"$ref":"#/components/schemas/GbpAuditCheck"},"type":"array","title":"Checks"}},"additionalProperties":false,"type":"object","required":["id","location_id","score","measured","total","counts"],"title":"GbpAuditRun","description":"A Business Profile audit run: the 0 to 100 score over the checks measured, its coverage and every check."},"GbpFieldStatus":{"properties":{"field_id":{"type":"string","title":"Field Id"},"label":{"type":"string","title":"Label"},"status":{"type":"string","enum":["complete","incomplete","needs_improvement"],"title":"Status"},"detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detail"}},"additionalProperties":false,"type":"object","required":["field_id","label","status"],"title":"GbpFieldStatus","description":"How complete one field of the profile is."},"GbpHoursPeriod":{"properties":{"open_day":{"type":"string","title":"Open Day"},"open_hour":{"type":"integer","maximum":23.0,"minimum":0.0,"title":"Open Hour"},"open_minute":{"type":"integer","maximum":59.0,"minimum":0.0,"title":"Open Minute"},"close_day":{"type":"string","title":"Close Day"},"close_hour":{"type":"integer","maximum":24.0,"minimum":0.0,"title":"Close Hour"},"close_minute":{"type":"integer","maximum":59.0,"minimum":0.0,"title":"Close Minute"}},"additionalProperties":false,"type":"object","required":["open_day","open_hour","open_minute","close_day","close_hour","close_minute"],"title":"GbpHoursPeriod","description":"One open and close window of a week; days are `MONDAY` to `SUNDAY`, hours 0 to 24."},"GbpKeyword":{"properties":{"keyword":{"type":"string","title":"Keyword"},"impressions":{"type":"integer","minimum":0.0,"title":"Impressions","default":0},"threshold":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Threshold","description":"Set when Google reports only that impressions are below this number."}},"additionalProperties":false,"type":"object","required":["keyword"],"title":"GbpKeyword","description":"A search people used to find the location, with its impressions."},"GbpKeywords":{"properties":{"month":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Month"},"keywords":{"items":{"$ref":"#/components/schemas/GbpKeyword"},"type":"array","title":"Keywords"}},"additionalProperties":false,"type":"object","title":"GbpKeywords","description":"The searches of one month."},"GbpLocation":{"properties":{"object":{"type":"string","const":"gbp_location","title":"Object","description":"Always `gbp_location`.","default":"gbp_location"},"id":{"type":"string","title":"Id","description":"The linked location's id, the `location_id` the other GBP endpoints take."},"gbp_account_id":{"type":"string","title":"Gbp Account Id","description":"Google's account id."},"gbp_location_id":{"type":"string","title":"Gbp Location Id","description":"Google's location id."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"The location's name on Google."},"is_primary":{"type":"boolean","title":"Is Primary","description":"The brand's main location."},"place_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Place Id","description":"Google place id, once a geo-grid scan resolved it."},"latitude":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Latitude"},"longitude":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Longitude"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"format":"date-time","title":"Created At"}},"additionalProperties":false,"type":"object","required":["id","gbp_account_id","gbp_location_id","is_primary"],"title":"GbpLocation","description":"A Google Business Profile location linked to the brand."},"GbpLocationList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/GbpLocation"},"type":"array","title":"Data"}},"additionalProperties":false,"type":"object","required":["data"],"title":"GbpLocationList","description":"Every location linked to the brand."},"GbpPerformance":{"properties":{"object":{"type":"string","const":"gbp_performance","title":"Object","description":"Always `gbp_performance`.","default":"gbp_performance"},"location_id":{"type":"string","title":"Location Id"},"date_range_start":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Date Range Start"},"date_range_end":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Date Range End"},"totals":{"additionalProperties":{"type":"integer"},"type":"object","title":"Totals","description":"Each metric summed over the window."},"totals_prev":{"anyOf":[{"additionalProperties":{"type":"integer"},"type":"object"},{"type":"null"}],"title":"Totals Prev","description":"The same over the window before."},"prev_period_start":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prev Period Start"},"prev_period_end":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prev Period End"},"metrics":{"items":{"$ref":"#/components/schemas/GbpPerformanceDay"},"type":"array","title":"Metrics","description":"One row per day."},"keywords":{"anyOf":[{"$ref":"#/components/schemas/GbpKeywords"},{"type":"null"}],"description":"With `include=keywords`."}},"additionalProperties":false,"type":"object","required":["location_id"],"title":"GbpPerformance","description":"The location's daily performance in the window, its totals and the previous window's."},"GbpPerformanceDay":{"properties":{"date":{"type":"string","title":"Date"},"business_impressions_desktop_maps":{"type":"integer","title":"Business Impressions Desktop Maps","default":0},"business_impressions_desktop_search":{"type":"integer","title":"Business Impressions Desktop Search","default":0},"business_impressions_mobile_maps":{"type":"integer","title":"Business Impressions Mobile Maps","default":0},"business_impressions_mobile_search":{"type":"integer","title":"Business Impressions Mobile Search","default":0},"website_clicks":{"type":"integer","title":"Website Clicks","default":0},"call_clicks":{"type":"integer","title":"Call Clicks","default":0},"business_direction_requests":{"type":"integer","title":"Business Direction Requests","default":0},"business_bookings":{"type":"integer","title":"Business Bookings","default":0},"business_food_orders":{"type":"integer","title":"Business Food Orders","default":0},"business_conversations":{"type":"integer","title":"Business Conversations","default":0}},"additionalProperties":false,"type":"object","required":["date"],"title":"GbpPerformanceDay","description":"One day of the location's actions and impressions on Google."},"GbpPost":{"properties":{"topic_type":{"type":"string","enum":["STANDARD","EVENT","OFFER"],"title":"Topic Type","default":"STANDARD"},"summary":{"type":"string","maxLength":1500,"minLength":1,"title":"Summary","description":"The post's text."},"media_urls":{"items":{"type":"string"},"type":"array","maxItems":10,"title":"Media Urls","description":"Up to 10 public photo URLs."},"call_to_action_type":{"anyOf":[{"type":"string","enum":["BOOK","ORDER","SHOP","LEARN_MORE","SIGN_UP","CALL"]},{"type":"null"}],"title":"Call To Action Type"},"call_to_action_url":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Call To Action Url","description":"Not used with `CALL`."},"event_title":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Event Title","description":"`EVENT` and `OFFER` posts."},"event_start":{"anyOf":[{"type":"string","maxLength":30},{"type":"null"}],"title":"Event Start","description":"ISO 8601."},"event_end":{"anyOf":[{"type":"string","maxLength":30},{"type":"null"}],"title":"Event End","description":"ISO 8601."},"offer_coupon_code":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Offer Coupon Code","description":"`OFFER` posts."}},"additionalProperties":false,"type":"object","required":["summary"],"title":"GbpPost","description":"A local post, as Google takes it."},"GbpPostSchedule":{"properties":{"object":{"type":"string","const":"gbp_post_schedule","title":"Object","default":"gbp_post_schedule"},"id":{"type":"string","title":"Id"},"location_id":{"type":"string","title":"Location Id","description":"The linked location it publishes on."},"status":{"type":"string","title":"Status","description":"`scheduled`, `publishing`, `published`, `failed`, `canceled`, `held` (its time came while the brand owner's plan did not include it; it goes out if the plan is back within two hours of its time) or `missed` (it waited longer than that; it never goes out on its own, rescheduling it puts it back in the queue)."},"scheduled_at":{"type":"string","format":"date-time","title":"Scheduled At","description":"When it publishes."},"is_active":{"type":"boolean","title":"Is Active"},"last_error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Error Message"},"published_post_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Published Post Id","description":"Google's post id once published."},"post":{"additionalProperties":true,"type":"object","title":"Post","description":"The post as it will be sent."},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"format":"date-time","title":"Created At"}},"additionalProperties":false,"type":"object","required":["id","location_id","status","scheduled_at","is_active","post"],"title":"GbpPostSchedule","description":"A scheduled local post."},"GbpPostScheduleCreate":{"properties":{"scheduled_at":{"type":"string","format":"date-time","title":"Scheduled At","description":"When to publish; must be in the future. A time without a zone is UTC."},"post":{"$ref":"#/components/schemas/GbpPost"}},"additionalProperties":false,"type":"object","required":["scheduled_at","post"],"title":"GbpPostScheduleCreate","description":"A post to publish on the location at a future time.","example":{"post":{"call_to_action_type":"LEARN_MORE","call_to_action_url":"https://www.rankprompt.com","summary":"Our autumn menu is here: seasonal pastries every morning."},"scheduled_at":"2026-10-20T14:00:00Z"}},"GbpPostScheduleList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/GbpPostSchedule"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"True when more items exist past this page. Fetch them with a larger `offset`."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of items matching the query, across all pages."},"limit":{"type":"integer","minimum":1.0,"title":"Limit","description":"Page size that was applied."},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of items skipped before this page."}},"additionalProperties":false,"type":"object","required":["data","has_more","total","limit","offset"],"title":"GbpPostScheduleList","description":"A page of the brand's pending scheduled posts, across its locations."},"GbpPostScheduleUpdate":{"properties":{"scheduled_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Scheduled At","description":"The new time to publish; must be in the future. A time without a zone is UTC. Required to reschedule a `missed` post."},"post":{"anyOf":[{"$ref":"#/components/schemas/GbpPost"},{"type":"null"}],"description":"The new body, replacing the whole post."}},"additionalProperties":false,"type":"object","title":"GbpPostScheduleUpdate","description":"A new time, a new body, or both, for a pending scheduled post; at least one.","example":{"scheduled_at":"2026-10-22T09:00:00Z"}},"GbpProfile":{"properties":{"object":{"type":"string","const":"gbp_profile","title":"Object","description":"Always `gbp_profile`.","default":"gbp_profile"},"location_id":{"type":"string","title":"Location Id","description":"The linked location's id."},"gbp_location_id":{"type":"string","title":"Gbp Location Id","description":"Google's location id."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"website_uri":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Website Uri"},"primary_phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Primary Phone"},"primary_category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Primary Category"},"primary_category_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Primary Category Id"},"additional_categories":{"items":{"type":"string"},"type":"array","title":"Additional Categories"},"additional_category_ids":{"items":{"type":"string"},"type":"array","title":"Additional Category Ids"},"address_lines":{"items":{"type":"string"},"type":"array","title":"Address Lines"},"locality":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Locality"},"region":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Region"},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Postal Code"},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country"},"formatted_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Formatted Address"},"service_items":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Service Items","description":"The services listed, as Google has them."},"regular_hours_summary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Regular Hours Summary"},"regular_hours_periods":{"items":{"$ref":"#/components/schemas/GbpHoursPeriod"},"type":"array","title":"Regular Hours Periods"},"special_hours_summary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Special Hours Summary"},"open_for_business":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Open For Business"},"maps_uri":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Maps Uri"},"new_review_uri":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"New Review Uri","description":"The link that opens a new review of the location."},"description_locked":{"type":"boolean","title":"Description Locked","description":"Google refuses edits of the description for this kind of business.","default":false},"description_locked_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description Locked Reason"},"audit":{"$ref":"#/components/schemas/GbpAudit"}},"additionalProperties":false,"type":"object","required":["location_id","gbp_location_id","audit"],"title":"GbpProfile","description":"A linked location's Business Profile as Google has it, with its latest audit."},"GbpProfileUpdate":{"properties":{"profile_description":{"anyOf":[{"type":"string","maxLength":750},{"type":"null"}],"title":"Profile Description"},"website_uri":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Website Uri"},"primary_phone":{"anyOf":[{"type":"string","maxLength":30},{"type":"null"}],"title":"Primary Phone"},"regular_hours":{"anyOf":[{"items":{"$ref":"#/components/schemas/GbpHoursPeriod"},"type":"array","maxItems":50},{"type":"null"}],"title":"Regular Hours","description":"Every open window of the week, replacing the hours."},"primary_category_id":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Primary Category Id"},"additional_category_ids":{"anyOf":[{"items":{"type":"string","maxLength":200},"type":"array","maxItems":9},{"type":"null"}],"title":"Additional Category Ids"},"service_items":{"anyOf":[{"items":{"type":"string","maxLength":140},"type":"array","maxItems":100},{"type":"null"}],"title":"Service Items","description":"Free-form service labels to replace the entire serviceItems list"},"service_descriptions":{"anyOf":[{"additionalProperties":{"type":"string","maxLength":300},"propertyNames":{"maxLength":140},"type":"object","maxProperties":100},{"type":"null"}],"title":"Service Descriptions"}},"additionalProperties":false,"type":"object","title":"GbpProfileUpdate","description":"The profile fields to write on Google; only the ones given change.","example":{"profile_description":"Family dental clinic in Austin with same-day appointments.","service_items":["Teeth cleaning","Whitening"],"website_uri":"https://www.rankprompt.com"}},"GbpReview":{"properties":{"object":{"type":"string","const":"gbp_review","title":"Object","default":"gbp_review"},"review_id":{"type":"string","title":"Review Id"},"reviewer_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reviewer Name"},"star_rating":{"anyOf":[{"type":"integer","maximum":5.0,"minimum":1.0},{"type":"null"}],"title":"Star Rating"},"comment":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Comment"},"create_time":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Create Time"},"update_time":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Update Time"},"reply_comment":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reply Comment"},"reply_time":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reply Time"},"reply_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reply State","description":"`APPROVED`, `PENDING_APPROVAL` or `FILTERED`."}},"additionalProperties":false,"type":"object","required":["review_id"],"title":"GbpReview","description":"A Google review and the reply it has, if any."},"GbpReviewList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/GbpReview"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Opaque continuation token. Pass back as `?cursor=` to fetch the next page. `null` when `has_more` is false."},"total_review_count":{"type":"integer","minimum":0.0,"title":"Total Review Count"},"average_rating":{"type":"number","title":"Average Rating"}},"additionalProperties":false,"type":"object","required":["data","has_more","total_review_count","average_rating"],"title":"GbpReviewList","description":"A page of a location's reviews, newest first; `next_cursor` is Google's page token."},"GbpReviewReply":{"properties":{"object":{"type":"string","const":"gbp_review_reply","title":"Object","default":"gbp_review_reply"},"review_id":{"type":"string","title":"Review Id"},"comment":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Comment"},"update_time":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Update Time"}},"additionalProperties":false,"type":"object","required":["review_id"],"title":"GbpReviewReply","description":"The reply as Google holds it."},"GbpReviewReplyCreate":{"properties":{"comment":{"type":"string","maxLength":4096,"minLength":1,"title":"Comment"}},"additionalProperties":false,"type":"object","required":["comment"],"title":"GbpReviewReplyCreate","description":"The reply to publish under the review; it replaces the one there.","example":{"comment":"Thank you, we are glad you liked the new menu."}},"GeoScanAiComparison":{"properties":{"from_scan_id":{"type":"string","title":"From Scan Id"},"to_scan_id":{"type":"string","title":"To Scan Id"},"from_visibility_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"From Visibility Pct"},"to_visibility_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"To Visibility Pct"},"visibility_change":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Visibility Change","description":"Percentage points; negative is a drop."},"same_grid":{"type":"boolean","title":"Same Grid","description":"Both used the same grid around the same centre, so `cells` pairs each point."},"cells":{"items":{"$ref":"#/components/schemas/GeoScanAiComparisonCell"},"type":"array","title":"Cells"}},"additionalProperties":false,"type":"object","required":["from_scan_id","to_scan_id","same_grid"],"title":"GeoScanAiComparison","description":"The AI grids of the two scans' runs."},"GeoScanAiComparisonCell":{"properties":{"grid_row":{"type":"integer","title":"Grid Row"},"grid_col":{"type":"integer","title":"Grid Col"},"from_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"From Pct"},"to_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"To Pct"}},"additionalProperties":false,"type":"object","required":["grid_row","grid_col"],"title":"GeoScanAiComparisonCell"},"GeoScanAiGrids":{"properties":{"from_scan_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"From Scan Id","description":"The older scan's run's AI grid."},"to_scan_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"To Scan Id","description":"The newer scan's run's AI grid."},"from_visibility_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"From Visibility Pct"},"to_visibility_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"To Visibility Pct"}},"additionalProperties":false,"type":"object","title":"GeoScanAiGrids","description":"Each scan's run's completed AI grid; null for a run without one."},"GeoScanComparison":{"properties":{"object":{"type":"string","const":"geo_scan_comparison","title":"Object","description":"Always `geo_scan_comparison`.","default":"geo_scan_comparison"},"from_scan":{"$ref":"#/components/schemas/PlaceGeoScanSummary"},"to_scan":{"$ref":"#/components/schemas/PlaceGeoScanSummary"},"same_grid":{"type":"boolean","title":"Same Grid","description":"Both used the same grid around the same centre, so `cells` pairs each point."},"avg_rank_change":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Rank Change","description":"Positive is worse (a higher rank number)."},"top3_share_change":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Top3 Share Change","description":"Percentage points; negative is a drop."},"found_change":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Found Change"},"cells":{"items":{"$ref":"#/components/schemas/GeoScanComparisonCell"},"type":"array","title":"Cells"},"ai":{"anyOf":[{"$ref":"#/components/schemas/GeoScanAiComparison"},{"type":"null"}],"description":"Both scans' runs had a completed AI grid: its change; null otherwise."},"ai_grids":{"$ref":"#/components/schemas/GeoScanAiGrids","description":"Each scan's run's AI grid and its visibility, so a run with one shows even when the other has none."}},"additionalProperties":false,"type":"object","required":["from_scan","to_scan","same_grid"],"title":"GeoScanComparison","description":"Two completed scans of the place, oldest first, with what changed."},"GeoScanComparisonCell":{"properties":{"grid_row":{"type":"integer","title":"Grid Row"},"grid_col":{"type":"integer","title":"Grid Col"},"from_rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"From Rank"},"to_rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"To Rank"}},"additionalProperties":false,"type":"object","required":["grid_row","grid_col"],"title":"GeoScanComparisonCell"},"GeoScanCompetitor":{"properties":{"rank":{"type":"integer","title":"Rank"},"name":{"type":"string","title":"Name"},"place_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Place Id"},"rating":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Rating"},"reviews":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Reviews"},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category"},"address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address"},"website":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Website"},"lat":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Lat"},"lng":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Lng"}},"additionalProperties":false,"type":"object","required":["rank","name"],"title":"GeoScanCompetitor","description":"One business of the local pack at a grid point."},"GeoScanKeyword":{"properties":{"object":{"type":"string","const":"geo_scan_keyword","title":"Object","description":"Always `geo_scan_keyword`.","default":"geo_scan_keyword"},"keyword":{"type":"string","title":"Keyword"},"scans_count":{"type":"integer","title":"Scans Count"},"last_scan_id":{"type":"string","title":"Last Scan Id"},"last_scanned_at":{"type":"string","title":"Last Scanned At"},"avg_rank":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Rank"},"found_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Found Count"},"point_count":{"type":"integer","title":"Point Count"},"top3_share":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Top3 Share","description":"Share of the grid's points in the top 3, 0 to 100."},"previous_avg_rank":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Previous Avg Rank"},"previous_top3_share":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Previous Top3 Share"}},"additionalProperties":false,"type":"object","required":["keyword","scans_count","last_scan_id","last_scanned_at","point_count"],"title":"GeoScanKeyword","description":"A search the place has completed scans of: its newest scan and the change from the one before."},"GeoScanKeywordList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/GeoScanKeyword"},"type":"array","title":"Data"}},"additionalProperties":false,"type":"object","required":["data"],"title":"GeoScanKeywordList","description":"Every search the place has completed scans of, newest first."},"GeoScanPoint":{"properties":{"grid_row":{"type":"integer","title":"Grid Row"},"grid_col":{"type":"integer","title":"Grid Col"},"lat":{"type":"number","title":"Lat"},"lng":{"type":"number","title":"Lng"},"rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rank","description":"Its place in the local pack; null when it is not in it."},"local_pack":{"items":{"$ref":"#/components/schemas/GeoScanCompetitor"},"type":"array","title":"Local Pack"}},"additionalProperties":false,"type":"object","required":["grid_row","grid_col","lat","lng"],"title":"GeoScanPoint","description":"The location's rank at one point of the grid, and the local pack there."},"GeoScanTrend":{"properties":{"object":{"type":"string","const":"geo_scan_trend","title":"Object","description":"Always `geo_scan_trend`.","default":"geo_scan_trend"},"location_id":{"type":"string","title":"Location Id"},"keyword":{"type":"string","title":"Keyword"},"data":{"items":{"$ref":"#/components/schemas/GeoScanTrendPoint"},"type":"array","title":"Data"},"ai":{"items":{"$ref":"#/components/schemas/GeoScanTrendAi"},"type":"array","title":"Ai","description":"The place's completed AI grids in the same window, oldest first (every search shares them)."}},"additionalProperties":false,"type":"object","required":["location_id","keyword","data"],"title":"GeoScanTrend","description":"One search's completed scans of the place in the window, oldest first."},"GeoScanTrendAi":{"properties":{"scan_id":{"type":"string","title":"Scan Id"},"run_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run Id"},"at":{"type":"string","title":"At"},"visibility_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Visibility Pct","description":"Share of its answers naming the brand, 0 to 100."}},"additionalProperties":false,"type":"object","required":["scan_id","at"],"title":"GeoScanTrendAi"},"GeoScanTrendPoint":{"properties":{"scan_id":{"type":"string","title":"Scan Id"},"created_at":{"type":"string","title":"Created At"},"grid_size":{"type":"integer","title":"Grid Size"},"point_count":{"type":"integer","title":"Point Count"},"spacing_km":{"type":"number","title":"Spacing Km"},"avg_rank":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Rank"},"found_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Found Count"},"top3_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Top3 Count"},"top3_share":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Top3 Share"},"schedule_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Schedule Id"},"run_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run Id","description":"The run it belongs to; the AI grid of the same run has the same `run_id`."}},"additionalProperties":false,"type":"object","required":["scan_id","created_at","grid_size","point_count","spacing_km"],"title":"GeoScanTrendPoint"},"GitHubBlogScaffold":{"properties":{"object":{"type":"string","const":"github_blog_scaffold","title":"Object","default":"github_blog_scaffold"},"pull_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pull Url","description":"The pull request."},"pull_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Pull Number"},"files":{"items":{"type":"string"},"type":"array","title":"Files","description":"The files it adds."},"added_dependencies":{"items":{"type":"string"},"type":"array","title":"Added Dependencies","description":"Packages it adds to package.json."},"status":{"type":"string","enum":["no_blog","pending_scaffold","ready"],"title":"Status","description":"Always `pending_scaffold` until the pull request merges."}},"additionalProperties":false,"type":"object","required":["files","added_dependencies","status"],"title":"GitHubBlogScaffold","description":"The pull request opened to add a blog; the repo becomes a publish target once it merges."},"GitHubPublishingProfile":{"properties":{"object":{"type":"string","const":"github_publishing_profile","title":"Object","default":"github_publishing_profile"},"repo_full_name":{"type":"string","title":"Repo Full Name","description":"The connected repository, `owner/name`."},"default_branch":{"type":"string","title":"Default Branch","description":"The branch posts are written against."},"allowed_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Allowed Path","description":"The folder the connection may change, if scoped."},"status":{"anyOf":[{"type":"string","enum":["no_blog","pending_scaffold","ready"]},{"type":"null"}],"title":"Status","description":"`ready` (articles publish to it), `no_blog` (no blog found: a scaffold can add one), `pending_scaffold` (the pull request that adds a blog waits to be merged), or `null` before the repo was read."},"profile":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Profile","description":"How the blog is laid out: `framework`, `content_dir`, `path_template`, `format`, `frontmatter_map`, `images_mode`, `site_url`, `url_pattern`, `locales`, `default_locale`, `branch`, `commit_mode` (`pull_request` or `direct`), `confidence` and the `evidence` it was read from."},"scaffold_pull_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scaffold Pull Url","description":"The pull request that adds the blog, if opened."},"scaffold_supported":{"type":"boolean","title":"Scaffold Supported","description":"Whether a blog can be added to this framework automatically."},"publish_target_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Publish Target Id","description":"The CMS connection id to publish to once `ready`; `null` until then."},"notice":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notice","description":"`empty_blog` when a ready blog showed no posts and its saved profile was kept."}},"additionalProperties":false,"type":"object","required":["repo_full_name","default_branch","scaffold_supported"],"title":"GitHubPublishingProfile","description":"The saved publishing profile of the connected repo, its status and the scaffold pull request, if any.","example":{"default_branch":"main","object":"github_publishing_profile","profile":{"commit_mode":"pull_request","format":"mdx","framework":"astro","path_template":"src/content/blog/{slug}.mdx","site_url":"https://www.rankprompt.com","url_pattern":"/blog/{slug}"},"publish_target_id":"6a1f0c3e-8b2d-4e7f-9a1c-2d3e4f5a6b7c","repo_full_name":"rankprompt/website","scaffold_supported":true,"status":"ready"}},"GooglePlace":{"properties":{"rating":{"anyOf":[{"type":"number","maximum":5.0,"minimum":0.0},{"type":"null"}],"title":"Rating","description":"Google rating, 0 to 5."},"reviews":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Reviews","description":"Number of Google reviews."},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category","description":"Google Maps category, such as `Dentist`."},"address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address","description":"Address as Google shows it (the card's is short)."},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone","description":"Phone number from the Maps listing."},"position":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Position","description":"1-based position of the place among the places the answer lists."}},"type":"object","title":"GooglePlace","description":"What Google shows about a place a Google AI Mode (AI Overviews) answer cites."},"GoogleProperties":{"properties":{"object":{"type":"string","const":"google_properties","title":"Object","default":"google_properties"},"ga4_properties":{"items":{"$ref":"#/components/schemas/Ga4Property"},"type":"array","title":"Ga4 Properties"},"gsc_sites":{"items":{"$ref":"#/components/schemas/GscSite"},"type":"array","title":"Gsc Sites"},"ga4_property_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ga4 Property Id","description":"Currently selected property."},"gsc_site_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gsc Site Url","description":"Currently selected site."}},"additionalProperties":false,"type":"object","title":"GoogleProperties","description":"What the linked Google account offers, so a caller can pick the property and the site."},"GscCandidate":{"properties":{"keyword":{"type":"string","title":"Keyword"},"clicks":{"type":"integer","title":"Clicks"},"impressions":{"type":"integer","title":"Impressions"},"position":{"type":"number","title":"Position"}},"type":"object","required":["keyword","clicks","impressions","position"],"title":"GscCandidate"},"GscSite":{"properties":{"object":{"type":"string","const":"gsc_site","title":"Object","default":"gsc_site"},"site_url":{"type":"string","title":"Site Url","description":"Site as Search Console names it, e.g. `sc-domain:adidas.com`."},"permission_level":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Permission Level","description":"The account's permission on that site."}},"additionalProperties":false,"type":"object","required":["site_url"],"title":"GscSite","description":"A Search Console site the connected Google account can read."},"GscSitemap":{"properties":{"object":{"type":"string","const":"gsc_sitemap","title":"Object","default":"gsc_sitemap"},"path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Path","description":"Sitemap URL as submitted to Search Console."},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Type","description":"Sitemap type reported by Google (e.g. `sitemap`)."},"is_index":{"type":"boolean","title":"Is Index","description":"True when this is a sitemap index (points at child sitemaps).","default":false},"is_pending":{"type":"boolean","title":"Is Pending","description":"True while Google has not finished processing the sitemap.","default":false},"last_submitted":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Last Submitted","description":"When the sitemap was last submitted."},"last_downloaded":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Last Downloaded","description":"When Google last downloaded the sitemap."},"errors":{"type":"integer","minimum":0.0,"title":"Errors","description":"Error count reported by Google.","default":0},"warnings":{"type":"integer","minimum":0.0,"title":"Warnings","description":"Warning count reported by Google.","default":0},"submitted_urls":{"type":"integer","minimum":0.0,"title":"Submitted Urls","description":"Total URLs submitted across the sitemap contents.","default":0}},"additionalProperties":false,"type":"object","title":"GscSitemap","description":"One submitted sitemap and its Search Console indexing status.","example":{"errors":0,"is_index":false,"is_pending":false,"last_downloaded":"2026-06-02T03:14:00Z","last_submitted":"2026-06-01T09:00:00Z","object":"gsc_sitemap","path":"https://rankprompt.com/sitemap.xml","submitted_urls":342,"type":"sitemap","warnings":1}},"GscSitemapList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/GscSitemap"},"type":"array","title":"Data"},"connected":{"type":"boolean","title":"Connected","description":"True when a Search Console site is connected and readable."},"site_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Site Url","description":"Connected Search Console site the sitemaps belong to."}},"additionalProperties":false,"type":"object","required":["data","connected"],"title":"GscSitemapList","description":"Live sitemap-submission status, returning every submitted sitemap (not paginated).","example":{"connected":true,"data":[{"errors":0,"is_index":false,"is_pending":false,"last_downloaded":"2026-06-02T03:14:00Z","last_submitted":"2026-06-01T09:00:00Z","object":"gsc_sitemap","path":"https://rankprompt.com/sitemap.xml","submitted_urls":342,"type":"sitemap","warnings":1}],"object":"list","site_url":"sc-domain:rankprompt.com"}},"Heatmap":{"properties":{"object":{"type":"string","const":"portfolio_heatmap","title":"Object","default":"portfolio_heatmap"},"platforms":{"items":{"type":"string"},"type":"array","title":"Platforms"},"rows":{"items":{"$ref":"#/components/schemas/HeatmapRow"},"type":"array","title":"Rows"}},"additionalProperties":false,"type":"object","required":["platforms","rows"],"title":"Heatmap","description":"Brand by engine: how often each brand is named and its average rank."},"HeatmapCell":{"properties":{"platform":{"type":"string","title":"Platform"},"appearance_rate":{"type":"number","title":"Appearance Rate","description":"Percent of answers that named the brand."},"avg_rank":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Rank"}},"additionalProperties":false,"type":"object","required":["platform","appearance_rate"],"title":"HeatmapCell","description":"One engine for one brand."},"HeatmapRow":{"properties":{"brand_id":{"type":"string","title":"Brand Id"},"brand_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brand Name"},"cells":{"items":{"$ref":"#/components/schemas/HeatmapCell"},"type":"array","title":"Cells"}},"additionalProperties":false,"type":"object","required":["brand_id","cells"],"title":"HeatmapRow","description":"One brand across the engines."},"Job":{"properties":{"object":{"type":"string","title":"Object","description":"Always `job`.","default":"job"},"id":{"type":"string","title":"Id","description":"Job identifier (echoed back). Most dispatchers return a UUID, but some (e.g. brand-facts research) return a short URL-safe base64 id; treat as opaque."},"status":{"type":"string","enum":["pending","processing","completed","failed","cancelled"],"title":"Status","description":"Current job lifecycle status."},"step":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Step","description":"Current pipeline step (e.g. `generating_prompts`)."},"completed":{"type":"integer","minimum":0.0,"title":"Completed","description":"Items completed so far. Always ≤ `total` when `total > 0`.","default":0},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total items to process. `0` until the planner knows the size.","default":0},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message","description":"Human-readable status message."},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Updated At","description":"ISO-8601 timestamp of the last progress update."},"result":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Result","description":"On `completed`/`failed`, an opaque dict with provider details (e.g. `report_id`, `error`)."}},"additionalProperties":false,"type":"object","required":["id","status"],"title":"Job","description":"An async job.","example":{"completed":12,"id":"8c2f9c4b-1d8e-4f23-9a8b-13aa5e1f9020","message":"Fetching ChatGPT responses","object":"job","status":"processing","step":"fetching_results","total":30,"updated_at":"2026-04-01T11:42:11.117+00:00"}},"JobList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/Job"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Opaque continuation token. Pass back as `?cursor=` to fetch the next page. `null` when `has_more` is false."}},"additionalProperties":false,"type":"object","required":["data","has_more"],"title":"JobList","description":"Recent jobs for the caller. Cursor-paginated, newest first.","example":{"data":[{"completed":12,"id":"8c2f9c4b-1d8e-4f23-9a8b-13aa5e1f9020","message":"Fetching ChatGPT responses","object":"job","status":"processing","step":"fetching_results","total":30,"updated_at":"2026-04-01T11:42:11.117+00:00"}],"has_more":false,"object":"list"}},"KeywordArticle":{"properties":{"brief_id":{"type":"string","title":"Brief Id","description":"The article's content brief id."},"status":{"type":"string","enum":["planned","generating","ready","published","failed"],"title":"Status","description":"`planned` (scheduled draft), `generating`, `ready` (draft or in review), `published` or `failed`."},"published_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Published Url","description":"Where it was published, when it was."}},"type":"object","required":["brief_id","status"],"title":"KeywordArticle","description":"The newest article that targets the keyword (its topic or one of its target keywords)."},"KeywordCandidates":{"properties":{"object":{"type":"string","const":"keyword_candidates","title":"Object","default":"keyword_candidates"},"gsc":{"items":{"$ref":"#/components/schemas/GscCandidate"},"type":"array","title":"Gsc","description":"Search Console queries the site earns and does not track, the 50 with most impressions."},"gsc_connected":{"type":"boolean","title":"Gsc Connected"},"gsc_cached":{"type":"boolean","title":"Gsc Cached","description":"Search Console data has been pulled at least once; false means it never ran.","default":false},"prompts":{"items":{"$ref":"#/components/schemas/PromptCandidate"},"type":"array","title":"Prompts","description":"Keywords behind the brand's AI prompts, the 50 with most prompts."},"ranked":{"items":{"$ref":"#/components/schemas/RankedCandidate"},"type":"array","title":"Ranked","description":"Keywords the domain already ranks for, the 50 best placed."},"ranked_available":{"type":"boolean","title":"Ranked Available"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"}},"type":"object","required":["gsc","gsc_connected","prompts","ranked","ranked_available"],"title":"KeywordCandidates","description":"Keywords worth tracking, from the three sources the account already holds."},"KeywordCluster":{"properties":{"object":{"type":"string","const":"keyword_cluster","title":"Object","description":"Always `keyword_cluster`.","default":"keyword_cluster"},"id":{"type":"string","title":"Id"},"label":{"type":"string","title":"Label","description":"The pillar keyword."},"pillar_keyword_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pillar Keyword Id","description":"The pillar keyword's id."},"method":{"type":"string","enum":["serp","lexical"],"title":"Method","description":"`serp`: the members share 3 or more of the same pages in Google's top 10 with the pillar. `lexical`: no recent Google results to compare, grouped by wording until a SERP check places them."},"keyword_count":{"type":"integer","minimum":0.0,"title":"Keyword Count"},"total_volume":{"type":"integer","minimum":0.0,"title":"Total Volume","description":"Monthly searches summed over the members."},"avg_position":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Position","description":"Average position of the members that rank."},"ranking":{"type":"integer","minimum":0.0,"title":"Ranking","description":"Members ranking in the top 100."},"ai_overviews":{"type":"integer","minimum":0.0,"title":"Ai Overviews","description":"Members Google answers with an AI Overview."},"prompts":{"type":"integer","minimum":0.0,"title":"Prompts","description":"Report prompts whose head keyword is a member."},"articles_published":{"type":"integer","minimum":0.0,"title":"Articles Published"},"articles_in_progress":{"type":"integer","minimum":0.0,"title":"Articles In Progress","description":"Planned, being written or ready to publish."},"computed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Computed At","description":"When the clusters were last built."}},"type":"object","required":["id","label","method","keyword_count","total_volume","ranking","ai_overviews","prompts","articles_published","articles_in_progress"],"title":"KeywordCluster","description":"A topic: keywords Google answers with the same pages, led by the most searched one (the pillar)."},"KeywordClusterList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/KeywordCluster"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"True when more items exist past this page. Fetch them with a larger `offset`."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of items matching the query, across all pages."},"limit":{"type":"integer","minimum":1.0,"title":"Limit","description":"Page size that was applied."},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of items skipped before this page."}},"additionalProperties":false,"type":"object","required":["data","has_more","total","limit","offset"],"title":"KeywordClusterList","description":"A page of the brand's keyword clusters. Members: `GET /keywords?cluster_id=`."},"KeywordClusterRef":{"properties":{"id":{"type":"string","title":"Id"},"label":{"type":"string","title":"Label","description":"The cluster's name: its pillar keyword."},"is_pillar":{"type":"boolean","title":"Is Pillar","description":"This keyword leads the cluster."}},"type":"object","required":["id","label","is_pillar"],"title":"KeywordClusterRef","description":"The topic cluster a keyword sits in."},"KeywordClustersRecomputed":{"properties":{"object":{"type":"string","const":"keyword_clusters_recomputed","title":"Object","default":"keyword_clusters_recomputed"},"clusters":{"type":"integer","title":"Clusters"},"serp_clusters":{"type":"integer","title":"Serp Clusters"},"lexical_clusters":{"type":"integer","title":"Lexical Clusters"},"keywords_clustered":{"type":"integer","title":"Keywords Clustered"}},"type":"object","required":["clusters","serp_clusters","lexical_clusters","keywords_clustered"],"title":"KeywordClustersRecomputed"},"KeywordGap":{"properties":{"object":{"type":"string","const":"keyword_gap","title":"Object","default":"keyword_gap"},"target":{"$ref":"#/components/schemas/KeywordTarget"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"},"competitors":{"items":{"$ref":"#/components/schemas/GapCompetitorState"},"type":"array","title":"Competitors"},"competitors_total":{"type":"integer","title":"Competitors Total","description":"Competitors with a site, before `competitors_limit` trims `competitors` and `cache`.","default":0},"items":{"items":{"$ref":"#/components/schemas/KeywordGapItem"},"type":"array","title":"Items"},"items_total":{"type":"integer","title":"Items Total","description":"Gap keywords before `limit` and `offset`.","default":0},"cache":{"$ref":"#/components/schemas/GapCacheState","description":"Competitors a paid refresh would fetch."},"credits_charged":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Credits Charged","description":"Only on a refresh."}},"type":"object","required":["target","competitors","items","cache"],"title":"KeywordGap","description":"Keywords the brand's competitors rank for in Google that the brand's site does not."},"KeywordGapItem":{"properties":{"search_volume":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Search Volume","description":"Average monthly Google searches."},"cpc":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cpc","description":"Average cost per click, in USD."},"competition":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Competition","description":"Paid competition from 0 to 1."},"competition_level":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Competition Level","description":"`LOW`, `MEDIUM` or `HIGH`."},"keyword_difficulty":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Keyword Difficulty","description":"How hard it is to rank organically, 0 to 100."},"main_intent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Main Intent","description":"Search intent: informational, navigational, commercial or transactional."},"trend":{"anyOf":[{"$ref":"#/components/schemas/KeywordTrend"},{"type":"null"}]},"monthly_searches":{"anyOf":[{"items":{"$ref":"#/components/schemas/MonthlySearches"},"type":"array"},{"type":"null"}],"title":"Monthly Searches","description":"The last months' volume."},"serp_item_types":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Serp Item Types","description":"What Google shows on the results page."},"has_ai_overview":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Ai Overview","description":"Google answers this keyword with an AI Overview. Null where the results page was not bought, which is the case on the keyword gap and on ranked keywords."},"fetched_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Fetched At","description":"When these numbers were bought."},"keyword":{"type":"string","title":"Keyword"},"tracked":{"type":"boolean","title":"Tracked"},"related":{"type":"boolean","title":"Related","description":"Close to the keywords the brand already tracks or ranks for."},"competitors":{"items":{"$ref":"#/components/schemas/GapCompetitor"},"type":"array","title":"Competitors"}},"type":"object","required":["keyword","tracked","related","competitors"],"title":"KeywordGapItem"},"KeywordHistory":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/RankCheck"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Opaque continuation token. Pass back as `?cursor=` to fetch the next page. `null` when `has_more` is false."},"keyword":{"$ref":"#/components/schemas/TrackedKeyword"}},"additionalProperties":false,"type":"object","required":["data","has_more","keyword"],"title":"KeywordHistory","description":"One keyword with a page of its rank checks, newest first."},"KeywordLimits":{"properties":{"plan":{"type":"string","title":"Plan"},"tracked":{"type":"integer","title":"Tracked"},"tracked_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Tracked Limit","description":"Most keywords the plan can track; null is unlimited."},"checks_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Checks Limit","description":"Rank checks per day the plan allows."},"checks_today":{"type":"integer","title":"Checks Today"}},"type":"object","required":["plan","tracked","checks_today"],"title":"KeywordLimits"},"KeywordMetrics":{"properties":{"search_volume":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Search Volume","description":"Average monthly Google searches."},"cpc":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cpc","description":"Average cost per click, in USD."},"competition":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Competition","description":"Paid competition from 0 to 1."},"competition_level":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Competition Level","description":"`LOW`, `MEDIUM` or `HIGH`."},"keyword_difficulty":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Keyword Difficulty","description":"How hard it is to rank organically, 0 to 100."},"main_intent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Main Intent","description":"Search intent: informational, navigational, commercial or transactional."},"trend":{"anyOf":[{"$ref":"#/components/schemas/KeywordTrend"},{"type":"null"}]},"monthly_searches":{"anyOf":[{"items":{"$ref":"#/components/schemas/MonthlySearches"},"type":"array"},{"type":"null"}],"title":"Monthly Searches","description":"The last months' volume."},"serp_item_types":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Serp Item Types","description":"What Google shows on the results page."},"has_ai_overview":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Ai Overview","description":"Google answers this keyword with an AI Overview. Null where the results page was not bought, which is the case on the keyword gap and on ranked keywords."},"fetched_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Fetched At","description":"When these numbers were bought."}},"type":"object","title":"KeywordMetrics","description":"Google numbers for a keyword in the brand's market. Null when not fetched yet."},"KeywordMetricsLookup":{"properties":{"object":{"type":"string","const":"keyword_metrics_lookup","title":"Object","default":"keyword_metrics_lookup"},"items":{"items":{"$ref":"#/components/schemas/ResearchItem"},"type":"array","title":"Items","description":"One row per keyword, in the order sent; a keyword Google has no data for has null numbers."},"credits_used":{"type":"integer","title":"Credits Used"},"cached":{"type":"boolean","title":"Cached","description":"Every keyword was in the month's cache: nothing was charged."},"target":{"$ref":"#/components/schemas/KeywordTarget"}},"type":"object","required":["items","credits_used","cached","target"],"title":"KeywordMetricsLookup"},"KeywordMetricsLookupCreate":{"properties":{"keywords":{"items":{"type":"string"},"type":"array","maxItems":700,"minItems":1,"title":"Keywords","description":"Up to 700 keywords to price. Each is lowercased and read once; one past 80 characters or 10 words is left out."}},"additionalProperties":false,"type":"object","required":["keywords"],"title":"KeywordMetricsLookupCreate"},"KeywordPrompt":{"properties":{"prompt_text":{"type":"string","title":"Prompt Text"},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category"},"source":{"type":"string","enum":["llm","manual"],"title":"Source"},"runs":{"type":"integer","title":"Runs","description":"Completed runs of the prompt across reports."},"answers":{"type":"integer","title":"Answers","description":"Resolved AI answers across those runs; answers still being checked are left out."},"appearances":{"type":"integer","title":"Appearances","description":"Resolved answers that named the brand."},"report_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Report Id","description":"The newest completed report that ran it."},"difficulty":{"anyOf":[{"$ref":"#/components/schemas/PromptDifficulty"},{"type":"null"}]}},"type":"object","required":["prompt_text","source","runs","answers","appearances"],"title":"KeywordPrompt"},"KeywordPrompts":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/KeywordPrompt"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"True when more items exist past this page. Fetch them with a larger `offset`."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of items matching the query, across all pages."},"limit":{"type":"integer","minimum":1.0,"title":"Limit","description":"Page size that was applied."},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of items skipped before this page."},"keyword":{"type":"string","title":"Keyword"}},"additionalProperties":false,"type":"object","required":["data","has_more","total","limit","offset","keyword"],"title":"KeywordPrompts","description":"The prompts that stand for one keyword, most run first, a page at a time."},"KeywordResearch":{"properties":{"object":{"type":"string","const":"keyword_research","title":"Object","default":"keyword_research"},"seed":{"type":"string","title":"Seed"},"mode":{"type":"string","enum":["ideas","suggestions","suggestions_exact","related"],"title":"Mode"},"items":{"items":{"$ref":"#/components/schemas/ResearchItem"},"type":"array","title":"Items"},"seed_metrics":{"anyOf":[{"$ref":"#/components/schemas/ResearchSeed"},{"type":"null"}],"description":"The seed's own numbers, when the mode returns them."},"credits_used":{"type":"integer","title":"Credits Used"},"cached":{"type":"boolean","title":"Cached","description":"Served from the daily cache: nothing was charged."},"target":{"$ref":"#/components/schemas/KeywordTarget"}},"type":"object","required":["seed","mode","items","credits_used","cached","target"],"title":"KeywordResearch"},"KeywordResearchCreate":{"properties":{"seed":{"type":"string","maxLength":200,"minLength":2,"title":"Seed","description":"The keyword or topic to research."},"mode":{"type":"string","enum":["ideas","suggestions","suggestions_exact","related"],"title":"Mode","description":"`ideas`: related keywords by topic; `suggestions`: longer phrasings that contain the seed; `suggestions_exact`: only phrasings with the seed word for word; `related`: what Google lists as related searches.","default":"suggestions"}},"additionalProperties":false,"type":"object","required":["seed"],"title":"KeywordResearchCreate"},"KeywordSelection":{"properties":{"keyword_ids":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":1000},{"type":"null"}],"title":"Keyword Ids"}},"additionalProperties":false,"type":"object","title":"KeywordSelection","description":"Which tracked keywords an action applies to; omit for all of them."},"KeywordSerp":{"properties":{"people_also_ask":{"items":{"$ref":"#/components/schemas/PeopleAlsoAsk"},"type":"array","title":"People Also Ask","description":"The People also ask questions, in the order Google listed them."},"related_searches":{"items":{"type":"string"},"type":"array","title":"Related Searches","description":"Related searches and People also search for, as Google listed them."},"ai_overview":{"anyOf":[{"$ref":"#/components/schemas/SerpAiOverview"},{"type":"null"}],"description":"Null when the page had none."},"featured_snippet":{"anyOf":[{"$ref":"#/components/schemas/SerpFeaturedSnippet"},{"type":"null"}],"description":"Null when the page had none."},"discussions":{"anyOf":[{"items":{"$ref":"#/components/schemas/SerpDiscussion"},"type":"array"},{"type":"null"}],"title":"Discussions","description":"The threads on the page. Only a keyword's history carries them; null elsewhere."},"videos":{"anyOf":[{"items":{"$ref":"#/components/schemas/SerpVideo"},"type":"array"},{"type":"null"}],"title":"Videos","description":"The videos on the page. Only a keyword's history carries them; null elsewhere."},"checked_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Checked At","description":"When the rank check read this page."}},"type":"object","title":"KeywordSerp","description":"What Google showed around the keyword at its last rank check, shared by every brand tracking it there."},"KeywordSummary":{"properties":{"tracked":{"type":"integer","title":"Tracked","description":"Keywords rank tracked."},"saved":{"type":"integer","title":"Saved","description":"Keywords saved without rank checks.","default":0},"checked":{"type":"integer","title":"Checked","description":"Keywords checked at least once."},"ranking":{"type":"integer","title":"Ranking","description":"Keywords the site ranks for in the top 100."},"top_3":{"type":"integer","title":"Top 3"},"top_10":{"type":"integer","title":"Top 10"},"avg_position":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Position"},"improved":{"type":"integer","title":"Improved","description":"Keywords that moved up at the last check."},"declined":{"type":"integer","title":"Declined","description":"Keywords that moved down at the last check."},"last_checked_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Last Checked At"}},"type":"object","required":["tracked","checked","ranking","top_3","top_10","improved","declined"],"title":"KeywordSummary"},"KeywordTarget":{"properties":{"location_code":{"type":"integer","title":"Location Code","description":"Google location code of the brand's market."},"language_code":{"type":"string","title":"Language Code","description":"Language code of the brand's market."}},"type":"object","required":["location_code","language_code"],"title":"KeywordTarget","description":"The Google market the numbers are for."},"KeywordTrackingUpdate":{"properties":{"ids":{"items":{"type":"string"},"type":"array","maxItems":1000,"minItems":1,"title":"Ids","description":"Keyword ids, up to 1,000."},"rank_tracked":{"type":"boolean","title":"Rank Tracked","description":"`true` counts them against the plan's tracking cap."}},"additionalProperties":false,"type":"object","required":["ids","rank_tracked"],"title":"KeywordTrackingUpdate","description":"Turn rank checks on or off for keywords of the library."},"KeywordTrackingUpdated":{"properties":{"object":{"type":"string","const":"keyword_tracking_updated","title":"Object","default":"keyword_tracking_updated"},"updated":{"type":"integer","title":"Updated","description":"Keywords whose tracking changed."},"unchanged":{"type":"integer","title":"Unchanged","description":"Keywords already in the asked state."},"rank_tracked":{"type":"boolean","title":"Rank Tracked"}},"type":"object","required":["updated","unchanged","rank_tracked"],"title":"KeywordTrackingUpdated"},"KeywordTrend":{"properties":{"monthly":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Monthly","description":"Change over the last month, percent."},"quarterly":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Quarterly","description":"Change over the last quarter, percent."},"yearly":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Yearly","description":"Change over the last year, percent."}},"type":"object","title":"KeywordTrend"},"KeywordUpdate":{"properties":{"target_url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Target Url","description":"The page that should rank for the keyword; null clears it."},"starred":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Starred","description":"Star or unstar the keyword."}},"additionalProperties":false,"type":"object","title":"KeywordUpdate"},"KeywordsAdded":{"properties":{"object":{"type":"string","const":"tracked_keywords_added","title":"Object","default":"tracked_keywords_added"},"added":{"items":{"$ref":"#/components/schemas/TrackedKeyword"},"type":"array","title":"Added"},"skipped":{"type":"integer","title":"Skipped","description":"Keywords already tracked."},"credits_charged":{"type":"integer","title":"Credits Charged","description":"Credits spent buying the new keywords' Google numbers."}},"type":"object","required":["added","skipped","credits_charged"],"title":"KeywordsAdded"},"KeywordsCreate":{"properties":{"keywords":{"items":{"type":"string"},"type":"array","maxItems":1000,"minItems":1,"title":"Keywords","description":"Up to 1,000 keywords; duplicates are skipped."},"source":{"type":"string","enum":["manual","gsc","prompt","research","ranked","gap","fanout","serp","copilot"],"title":"Source","description":"Where they came from.","default":"manual"},"target_url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Target Url","description":"The page that should rank for them."},"rank_tracked":{"type":"boolean","title":"Rank Tracked","description":"Also check their Google rankings (counts against the plan's tracking cap and turns tracking on for keywords already saved); `false` only saves them, free and uncapped.","default":true}},"additionalProperties":false,"type":"object","required":["keywords"],"title":"KeywordsCreate","description":"Keywords to start tracking."},"KnowledgeItem":{"properties":{"object":{"type":"string","const":"knowledge_item","title":"Object","default":"knowledge_item"},"id":{"type":"string","title":"Id"},"title":{"type":"string","title":"Title"},"kind":{"type":"string","enum":["text","pdf","image","url","docx","md","txt","csv","sitemap_page","notion","google_drive"],"title":"Kind","description":"What it was added as; `sitemap_page` came from a site section, `notion` from a connected Notion page, `google_drive` from a Google Doc or Sheet picked in Google Drive."},"status":{"type":"string","enum":["processing","ready","failed"],"title":"Status","description":"`processing` while it is read and split into passages, `ready` when articles can use it."},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"When `failed`: `empty`, `unreadable`, `fetch_failed`, `too_large` or `internal`."},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Url","description":"The page it was read from, for URL items."},"char_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Char Count","description":"Characters of text read from it."},"enabled":{"type":"boolean","title":"Enabled","description":"False keeps it listed but out of every article."},"tags":{"items":{"type":"string"},"type":"array","title":"Tags"},"effective_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Effective Date","description":"When its facts were true; a later item wins when two disagree."},"refresh_interval_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Refresh Interval Days","description":"For URL items: re-read this often."},"last_fetched_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Last Fetched At","description":"When its page was last read."},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Created At"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Updated At"}},"additionalProperties":false,"type":"object","required":["id","title","kind","status","enabled"],"title":"KnowledgeItem","description":"One item of the knowledge base: a note, a file or a web page, and whether it is searchable yet."},"KnowledgeItemCreate":{"properties":{"type":{"type":"string","enum":["text","url"],"title":"Type"},"title":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Title","description":"Required for `text`; a page's own by default."},"content":{"anyOf":[{"type":"string","maxLength":200000},{"type":"null"}],"title":"Content","description":"The note, for `text`."},"url":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Url","description":"The page to read, for `url`."},"refresh_interval_days":{"anyOf":[{"type":"integer","maximum":365.0,"minimum":1.0},{"type":"null"}],"title":"Refresh Interval Days","description":"For `url`: re-read this often."}},"additionalProperties":false,"type":"object","required":["type"],"title":"KnowledgeItemCreate","description":"A note (`title` and `content`) or a web page (`url`); files go to `POST .../knowledge-base/files`."},"KnowledgeItemList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/KnowledgeItem"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"True when more items exist past this page. Fetch them with a larger `offset`."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of items matching the query, across all pages."},"limit":{"type":"integer","minimum":1.0,"title":"Limit","description":"Page size that was applied."},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of items skipped before this page."}},"additionalProperties":false,"type":"object","required":["data","has_more","total","limit","offset"],"title":"KnowledgeItemList","description":"A page of the brand's knowledge base, newest first."},"KnowledgeItemUpdate":{"properties":{"title":{"anyOf":[{"type":"string","maxLength":200,"minLength":1},{"type":"null"}],"title":"Title"},"enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Enabled"},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":20},{"type":"null"}],"title":"Tags","description":"Up to 20 tags of up to 40 characters."},"effective_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Effective Date"},"refresh_interval_days":{"anyOf":[{"type":"integer","maximum":365.0,"minimum":1.0},{"type":"null"}],"title":"Refresh Interval Days"}},"additionalProperties":false,"type":"object","title":"KnowledgeItemUpdate","description":"Change what you send; send `refresh_interval_days: null` to stop re-reading a page."},"KnowledgeMatch":{"properties":{"object":{"type":"string","const":"knowledge_match","title":"Object","default":"knowledge_match"},"item_id":{"type":"string","title":"Item Id","description":"The knowledge item it belongs to."},"title":{"type":"string","title":"Title"},"heading_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Heading Path","description":"The headings above the passage in its document."},"content":{"type":"string","title":"Content"},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Url"},"effective_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Effective Date"},"similarity":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Similarity","description":"Cosine similarity to the query, 0 to 1."}},"additionalProperties":false,"type":"object","required":["item_id","title","content"],"title":"KnowledgeMatch","description":"A passage of the knowledge base and how close it is to the query."},"KnowledgeMatchList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/KnowledgeMatch"},"type":"array","title":"Data"}},"additionalProperties":false,"type":"object","required":["data"],"title":"KnowledgeMatchList","description":"The passages an article about the query would draw on, best first."},"LocalPilot":{"properties":{"object":{"type":"string","const":"local_pilot","title":"Object","description":"Always `local_pilot`.","default":"local_pilot"},"location_id":{"type":"string","title":"Location Id"},"enabled":{"type":"boolean","title":"Enabled"},"auto_publish_positive":{"type":"boolean","title":"Auto Publish Positive","description":"Replies to 4 and 5 star reviews publish without approval."},"next_run_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Next Run At"},"last_run_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Last Run At"},"usage":{"anyOf":[{"$ref":"#/components/schemas/LocalPilotUsage"},{"type":"null"}]},"waiting":{"type":"integer","title":"Waiting","description":"Drafts waiting for approval in the app (replies, posts, directories).","default":0}},"additionalProperties":false,"type":"object","required":["location_id","enabled","auto_publish_positive"],"title":"LocalPilot","description":"The weekly local pilot of a linked location: on or off, this month's use, and how many drafts wait."},"LocalPilotUpdate":{"properties":{"enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Enabled","description":"Turn the pilot on (its first week is drafted within the hour) or off."},"auto_publish_positive":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Auto Publish Positive","description":"Publish replies to 4 and 5 star reviews without approval; 1 to 3 stars always wait."}},"additionalProperties":false,"type":"object","title":"LocalPilotUpdate"},"LocalPilotUsage":{"properties":{"replies":{"type":"integer","title":"Replies","description":"Replies drafted this month."},"posts":{"type":"integer","title":"Posts","description":"Posts drafted this month."},"replies_cap":{"type":"integer","title":"Replies Cap","description":"Replies included per location and month."},"posts_cap":{"type":"integer","title":"Posts Cap","description":"Posts included per location and month."}},"additionalProperties":false,"type":"object","required":["replies","posts","replies_cap","posts_cap"],"title":"LocalPilotUsage"},"LocalScanCreate":{"properties":{"grid_size":{"type":"integer","title":"Grid Size","description":"N in the NxN grid (3, 5 or 7)","default":3},"spacing_km":{"anyOf":[{"type":"number","maximum":20.0,"exclusiveMinimum":0.0},{"type":"string","const":"auto"}],"title":"Spacing Km","description":"Distance between adjacent grid points, km, or \"auto\": the centre is read first and the spacing set off how far its results lie (0.4 of their median distance, at least 1 km when fewer than 10 come back, rounded to 0.1, 0.2, 0.3, 0.5, 1, 1.5, 2 or 5 km). Left out, it is auto.","default":"auto"},"center_lat":{"anyOf":[{"type":"number","maximum":90.0,"minimum":-90.0},{"type":"null"}],"title":"Center Lat","description":"The grid's centre; null uses the place's pin"},"center_lng":{"anyOf":[{"type":"number","maximum":180.0,"minimum":-180.0},{"type":"null"}],"title":"Center Lng"},"searches":{"items":{"type":"string"},"type":"array","maxItems":10,"minItems":1,"title":"Searches"},"prompts":{"items":{"type":"string"},"type":"array","maxItems":5,"minItems":1,"title":"Prompts","description":"Questions as a customer asks them, without the city (\"near me\" is fine): the point is the place."}},"additionalProperties":false,"type":"object","required":["searches","prompts"],"title":"LocalScanCreate","description":"Scan the place now: one Maps scan per search and one AI grid of the questions, on the same grid.","example":{"grid_size":3,"prompts":["best dentist near me","best emergency dentist near me"],"searches":["dentist","emergency dentist"],"spacing_km":1.5}},"LocalScanRun":{"properties":{"object":{"type":"string","const":"local_scan_run","title":"Object","description":"Always `local_scan_run`.","default":"local_scan_run"},"run_id":{"type":"string","title":"Run Id"},"data":{"items":{"$ref":"#/components/schemas/PlaceGeoScanSummary"},"type":"array","title":"Data","description":"One Maps scan per search."},"ai_scan":{"$ref":"#/components/schemas/AiGeoScan","description":"The AI grid of the questions, with its points."}},"additionalProperties":false,"type":"object","required":["run_id","data","ai_scan"],"title":"LocalScanRun","description":"What one local scan started, pending: the Maps scans and the AI grid share `run_id`."},"LocalScanRunAi":{"properties":{"id":{"type":"string","title":"Id"},"status":{"type":"string","enum":["pending","running","completed","failed"],"title":"Status","description":"`pending`, `running`, `completed` or `failed`."},"visibility_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Visibility Pct","description":"Share of its answers naming the brand, 0 to 100."},"cells_answered":{"type":"integer","title":"Cells Answered"},"cells_total":{"type":"integer","title":"Cells Total"},"credits_charged":{"type":"integer","title":"Credits Charged"},"last_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Error"}},"additionalProperties":false,"type":"object","required":["id","status","cells_answered","cells_total","credits_charged"],"title":"LocalScanRunAi","description":"The AI grid of a run, without its points: read them with `GET .../ai-geo-scans/{scan_id}`."},"LocalScanRunList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/LocalScanRunSummary"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Opaque continuation token. Pass back as `?cursor=` to fetch the next page. `null` when `has_more` is false."}},"additionalProperties":false,"type":"object","required":["data","has_more"],"title":"LocalScanRunList","description":"A page of a place's runs, newest first."},"LocalScanRunMaps":{"properties":{"id":{"type":"string","title":"Id"},"keyword":{"type":"string","title":"Keyword"},"status":{"type":"string","enum":["pending","running","completed","failed"],"title":"Status","description":"`pending`, `running`, `completed` or `failed`."},"point_count":{"type":"integer","title":"Point Count"},"avg_rank":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Rank"},"found_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Found Count"},"top3_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Top3 Count"},"last_error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Error Message"}},"additionalProperties":false,"type":"object","required":["id","keyword","status","point_count"],"title":"LocalScanRunMaps","description":"One Maps scan of a run, without its points: read them with `GET .../geo-scans/{scan_id}`."},"LocalScanRunSummary":{"properties":{"object":{"type":"string","const":"local_scan_run","title":"Object","description":"Always `local_scan_run`.","default":"local_scan_run"},"run_id":{"type":"string","title":"Run Id"},"created_at":{"type":"string","title":"Created At"},"schedule_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Schedule Id","description":"The schedule that ran it; null for a run started by hand."},"searches":{"items":{"type":"string"},"type":"array","title":"Searches"},"prompts":{"items":{"type":"string"},"type":"array","title":"Prompts"},"grid_size":{"type":"integer","title":"Grid Size"},"spacing_km":{"type":"number","title":"Spacing Km"},"maps":{"items":{"$ref":"#/components/schemas/LocalScanRunMaps"},"type":"array","title":"Maps"},"ai":{"anyOf":[{"$ref":"#/components/schemas/LocalScanRunAi"},{"type":"null"}]}},"additionalProperties":false,"type":"object","required":["run_id","created_at","searches","prompts","grid_size","spacing_km","maps"],"title":"LocalScanRunSummary","description":"One run of the place: its Maps scans and its AI grid on one grid. A scan that ran alone (before runs, or an AI\ngrid by itself) is a run of its own, so `maps` may be empty and `ai` null."},"LocalScanSchedule":{"properties":{"object":{"type":"string","const":"local_scan_schedule","title":"Object","description":"Always `local_scan_schedule`.","default":"local_scan_schedule"},"id":{"type":"string","title":"Id"},"location_id":{"type":"string","title":"Location Id"},"keywords":{"items":{"type":"string"},"type":"array","title":"Keywords"},"prompts":{"items":{"type":"string"},"type":"array","title":"Prompts","description":"Questions for Gemini with Google Maps each run asks; none scans Maps only."},"grid_size":{"type":"integer","title":"Grid Size"},"spacing_km":{"type":"number","title":"Spacing Km","description":"The spacing of its runs, km; not read while `spacing_auto` is on."},"spacing_auto":{"type":"boolean","title":"Spacing Auto","description":"Each run reads the grid's centre first and sets its own spacing off it (`spacing_km: auto`).","default":false},"center_lat":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Center Lat"},"center_lng":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Center Lng"},"frequency":{"type":"string","enum":["off","daily","weekly","monthly"],"title":"Frequency"},"next_run_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Run At"},"paused_reason":{"anyOf":[{"type":"string","enum":["credits","place_archived"]},{"type":"null"}],"title":"Paused Reason","description":"`credits` or `place_archived`; saving the schedule resumes it."},"alert_rank_drop":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Alert Rank Drop"},"alert_top3_drop":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Alert Top3 Drop"},"last_run_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Run Id"},"last_run_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Run At"},"credits_per_run":{"type":"integer","title":"Credits Per Run"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"}},"additionalProperties":false,"type":"object","required":["id","location_id","keywords","grid_size","spacing_km","frequency","credits_per_run"],"title":"LocalScanSchedule"},"LocalScanScheduleCreate":{"properties":{"grid_size":{"type":"integer","title":"Grid Size","description":"N in the NxN grid (3, 5 or 7)","default":3},"spacing_km":{"anyOf":[{"type":"number","maximum":20.0,"exclusiveMinimum":0.0},{"type":"string","const":"auto"}],"title":"Spacing Km","description":"Distance between adjacent grid points, km, or \"auto\": the centre is read first and the spacing set off how far its results lie (0.4 of their median distance, at least 1 km when fewer than 10 come back, rounded to 0.1, 0.2, 0.3, 0.5, 1, 1.5, 2 or 5 km). Left out, it is auto.","default":"auto"},"center_lat":{"anyOf":[{"type":"number","maximum":90.0,"minimum":-90.0},{"type":"null"}],"title":"Center Lat","description":"The grid's centre; null uses the place's pin"},"center_lng":{"anyOf":[{"type":"number","maximum":180.0,"minimum":-180.0},{"type":"null"}],"title":"Center Lng"},"location_id":{"type":"string","title":"Location Id","description":"The place to scan."},"keywords":{"items":{"type":"string"},"type":"array","maxItems":10,"minItems":1,"title":"Keywords"},"prompts":{"items":{"type":"string"},"type":"array","maxItems":5,"title":"Prompts","description":"Questions asked of Gemini with Google Maps at every point on each run; none runs Maps only."},"frequency":{"type":"string","enum":["off","daily","weekly","monthly"],"title":"Frequency","default":"weekly"},"alert_rank_drop":{"anyOf":[{"type":"number","maximum":20.0,"exclusiveMinimum":0.0},{"type":"null"}],"title":"Alert Rank Drop","default":3.0},"alert_top3_drop":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":1.0},{"type":"null"}],"title":"Alert Top3 Drop","default":20}},"additionalProperties":false,"type":"object","required":["location_id","keywords"],"title":"LocalScanScheduleCreate","description":"A place's scheduled scans (``location_id`` is the place).","example":{"alert_rank_drop":3,"alert_top3_drop":20,"frequency":"weekly","grid_size":5,"keywords":["dentist","emergency dentist"],"location_id":"3f1c9a52-6d0e-4a8b-9c1d-2e4f6a8b0c1d","prompts":["best dentist near me"],"spacing_km":1.5}},"LocalScanScheduleList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/LocalScanSchedule"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Opaque continuation token. Pass back as `?cursor=` to fetch the next page. `null` when `has_more` is false."}},"additionalProperties":false,"type":"object","required":["data","has_more"],"title":"LocalScanScheduleList","description":"A page of the brand's map scan schedules, newest first."},"LocalScanScheduleUpdate":{"properties":{"keywords":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":10,"minItems":1},{"type":"null"}],"title":"Keywords"},"prompts":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":5},{"type":"null"}],"title":"Prompts"},"grid_size":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Grid Size"},"spacing_km":{"anyOf":[{"type":"number","maximum":20.0,"exclusiveMinimum":0.0},{"type":"string","const":"auto"},{"type":"null"}],"title":"Spacing Km","description":"Distance between adjacent grid points, km, or \"auto\": the centre is read first and the spacing set off how far its results lie (0.4 of their median distance, at least 1 km when fewer than 10 come back, rounded to 0.1, 0.2, 0.3, 0.5, 1, 1.5, 2 or 5 km)"},"center_lat":{"anyOf":[{"type":"number","maximum":90.0,"minimum":-90.0},{"type":"null"}],"title":"Center Lat"},"center_lng":{"anyOf":[{"type":"number","maximum":180.0,"minimum":-180.0},{"type":"null"}],"title":"Center Lng"},"frequency":{"anyOf":[{"type":"string","enum":["off","daily","weekly","monthly"]},{"type":"null"}],"title":"Frequency"},"alert_rank_drop":{"anyOf":[{"type":"number","maximum":20.0,"exclusiveMinimum":0.0},{"type":"null"}],"title":"Alert Rank Drop"},"alert_top3_drop":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":1.0},{"type":"null"}],"title":"Alert Top3 Drop"}},"additionalProperties":false,"type":"object","title":"LocalScanScheduleUpdate","description":"Only the fields sent change; saving resumes a paused schedule."},"Location":{"properties":{"object":{"type":"string","const":"location","title":"Object","description":"Always `location`.","default":"location"},"id":{"type":"string","title":"Id"},"brand_id":{"type":"string","title":"Brand Id"},"name":{"type":"string","title":"Name"},"source":{"type":"string","enum":["gbp","manual","csv"],"title":"Source","description":"`gbp` (imported from Google Business Profile), `manual` or `csv`."},"address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address"},"city":{"type":"string","title":"City"},"region":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Region"},"country":{"type":"string","title":"Country","description":"Full English country name."},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Postal Code"},"ai_location_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ai Location Label","description":"What the AI engines are told the location is; null sends `city`."},"latitude":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Latitude"},"longitude":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Longitude"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone"},"website":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Website"},"primary_category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Primary Category"},"google_linked":{"type":"boolean","title":"Google Linked","description":"Whether it is linked to one of the brand's Google Business Profile locations."},"is_primary":{"type":"boolean","title":"Is Primary","description":"The brand's main place; at most one."},"status":{"type":"string","enum":["active","archived"],"title":"Status","description":"`archived` places are never deleted: their markets keep their history."},"external_ref":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Ref","description":"Your own id for the place."},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Updated At"}},"additionalProperties":false,"type":"object","required":["id","brand_id","name","source","city","country","google_linked","is_primary","status","created_at"],"title":"Location","description":"One of the brand's real places: a store, office or branch its reports can measure as a market.","example":{"address":"1100 S Lamar Blvd","brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","city":"Austin","country":"United States","created_at":"2026-10-20T10:00:00+00:00","google_linked":true,"id":"5c1e2f3a-4b5c-4d6e-8f70-112233445566","is_primary":true,"latitude":30.2559,"longitude":-97.7647,"name":"Brooks Running Austin","object":"location","postal_code":"78704","primary_category":"Shoe store","region":"Texas","source":"gbp","status":"active","updated_at":"2026-10-20T10:00:00+00:00","website":"https://www.brooksrunning.com"}},"LocationCreate":{"properties":{"name":{"type":"string","maxLength":200,"minLength":1,"title":"Name"},"address":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Address"},"city":{"type":"string","maxLength":200,"minLength":1,"title":"City"},"region":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Region"},"country":{"type":"string","maxLength":100,"minLength":1,"title":"Country"},"postal_code":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Postal Code"},"ai_location_label":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Ai Location Label","description":"What the engines get; empty sends city."},"latitude":{"anyOf":[{"type":"number","maximum":90.0,"minimum":-90.0},{"type":"null"}],"title":"Latitude"},"longitude":{"anyOf":[{"type":"number","maximum":180.0,"minimum":-180.0},{"type":"null"}],"title":"Longitude"},"phone":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Phone"},"website":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Website"},"primary_category":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Primary Category"},"is_primary":{"type":"boolean","title":"Is Primary","default":false},"external_ref":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"External Ref"}},"additionalProperties":false,"type":"object","required":["name","city","country"],"title":"LocationCreate","description":"Body for ``POST /v1/brands/{brand_id}/locations``: a place added by hand.","example":{"city":"Austin","country":"United States","is_primary":true,"name":"Brooks Running Austin"}},"LocationImport":{"properties":{"source":{"type":"string","enum":["gbp","csv"],"title":"Source"},"gbp_location_ids":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":250,"minItems":1},{"type":"null"}],"title":"Gbp Location Ids"},"csv":{"anyOf":[{"type":"string","maxLength":200000,"minLength":1},{"type":"null"}],"title":"Csv"}},"additionalProperties":false,"type":"object","required":["source"],"title":"LocationImport","description":"Body for ``POST /v1/brands/{brand_id}/locations/imports``.","example":{"source":"gbp"}},"LocationImported":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/Location"},"type":"array","title":"Data"}},"additionalProperties":false,"type":"object","required":["data"],"title":"LocationImported","description":"The places an import created or found already there."},"LocationList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/Location"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Opaque continuation token. Pass back as `?cursor=` to fetch the next page. `null` when `has_more` is false."}},"additionalProperties":false,"type":"object","required":["data","has_more"],"title":"LocationList","description":"A page of the brand's places, newest first."},"LocationUpdate":{"properties":{"status":{"anyOf":[{"type":"string","enum":["active","archived"]},{"type":"null"}],"title":"Status"},"name":{"anyOf":[{"type":"string","maxLength":200,"minLength":1},{"type":"null"}],"title":"Name"},"address":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Address"},"city":{"anyOf":[{"type":"string","maxLength":200,"minLength":1},{"type":"null"}],"title":"City"},"region":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Region"},"country":{"anyOf":[{"type":"string","maxLength":100,"minLength":1},{"type":"null"}],"title":"Country"},"postal_code":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Postal Code"},"ai_location_label":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Ai Location Label"},"latitude":{"anyOf":[{"type":"number","maximum":90.0,"minimum":-90.0},{"type":"null"}],"title":"Latitude"},"longitude":{"anyOf":[{"type":"number","maximum":180.0,"minimum":-180.0},{"type":"null"}],"title":"Longitude"},"phone":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Phone"},"website":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Website"},"primary_category":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Primary Category"},"is_primary":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Primary"}},"additionalProperties":false,"type":"object","title":"LocationUpdate","description":"Body for ``PATCH /v1/brands/{brand_id}/locations/{location_id}``: the fields to change, or `status`.","example":{"status":"archived"}},"Mailbox":{"properties":{"object":{"type":"string","const":"mailbox","title":"Object","default":"mailbox"},"id":{"type":"string","title":"Id","description":"Mailbox id; campaigns and sends name it as `mailbox_id`."},"provider":{"type":"string","enum":["gmail","outlook"],"title":"Provider","description":"`gmail` or `outlook` (Outlook.com and Microsoft 365)."},"email_address":{"type":"string","title":"Email Address","description":"The address emails go out from."},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name","description":"The sender name."},"status":{"type":"string","enum":["connected","expired"],"title":"Status","description":"`expired` when the provider's access lapsed; `POST /v1/me/mailbox-connection-links` with its `provider` reconnects it."},"is_default":{"type":"boolean","title":"Is Default","description":"The mailbox a send uses when none is named."},"daily_send_limit":{"type":"integer","minimum":1.0,"title":"Daily Send Limit","description":"The most emails it sends a day."},"effective_daily_limit":{"type":"integer","minimum":1.0,"title":"Effective Daily Limit","description":"Today's cap: lower than the limit while warming up."},"emails_sent_today":{"type":"integer","minimum":0.0,"title":"Emails Sent Today","description":"Emails it sent today."},"warming_up":{"type":"boolean","title":"Warming Up","description":"Whether today's cap is still ramping up to the daily limit."},"warmup_started_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Warmup Started At","description":"When the warmup started (`YYYY-MM-DD`)."},"email_signature":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email Signature","description":"HTML signature added to its emails."},"last_error_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Error Code","description":"Why the connection needs its owner, or null when it works. An open set (new values can appear): `token_expired`, `scope_missing`, `not_selected`, `auth_failed`, `permission_missing`, `site_unreachable`, `host_moved`, `app_uninstalled`, `rate_limited`, `vendor_down`."},"last_error_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Last Error At","description":"When `last_error_code` was set; null while the mailbox works."},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Created At","description":"When it was connected."}},"additionalProperties":false,"type":"object","required":["id","provider","email_address","status","is_default","daily_send_limit","effective_daily_limit","emails_sent_today","warming_up"],"title":"Mailbox","description":"A mailbox (Gmail, or Outlook and Microsoft 365) the account's outreach sends from.","example":{"created_at":"2026-09-30T10:00:00+00:00","daily_send_limit":50,"display_name":"adidas Partnerships","effective_daily_limit":20,"email_address":"outreach@e2e.test","email_signature":"<p>adidas Partnerships</p>","emails_sent_today":3,"id":"5e6f7081-92a3-4b4c-8d5e-6f708192a3b4","is_default":true,"object":"mailbox","provider":"gmail","status":"connected","warming_up":true,"warmup_started_at":"2026-09-30"}},"MailboxConnectionLink":{"properties":{"object":{"type":"string","const":"mailbox_connection_link","title":"Object","default":"mailbox_connection_link"},"url":{"type":"string","title":"Url","description":"Open it signed in to Rank Prompt with this key's account selected; it takes the user through the provider's consent (Google's or Microsoft's) and stores the mailbox."}},"additionalProperties":false,"type":"object","required":["url"],"title":"MailboxConnectionLink","description":"The link that connects a mailbox.","example":{"object":"mailbox_connection_link","url":"https://app.rankprompt.com/outreach/callback?start=gmail&source=api"}},"MailboxConnectionLinkCreate":{"properties":{"provider":{"type":"string","enum":["gmail","outlook"],"title":"Provider","description":"`gmail`, or `outlook` for Outlook.com and Microsoft 365 mailboxes.","default":"gmail"}},"additionalProperties":false,"type":"object","title":"MailboxConnectionLinkCreate","description":"Which provider the link connects.","example":{"provider":"outlook"}},"MailboxList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/Mailbox"},"type":"array","title":"Data"}},"additionalProperties":false,"type":"object","required":["data"],"title":"MailboxList","description":"The account's mailboxes, newest first.","example":{"data":[{"created_at":"2026-09-30T10:00:00+00:00","daily_send_limit":50,"display_name":"adidas Partnerships","effective_daily_limit":20,"email_address":"outreach@e2e.test","email_signature":"<p>adidas Partnerships</p>","emails_sent_today":3,"id":"5e6f7081-92a3-4b4c-8d5e-6f708192a3b4","is_default":true,"object":"mailbox","provider":"gmail","status":"connected","warming_up":true,"warmup_started_at":"2026-09-30"}],"object":"list"}},"MailboxUpdate":{"properties":{"display_name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Display Name","description":"The sender name."},"is_default":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Default","description":"`true` makes it the default mailbox."},"daily_send_limit":{"anyOf":[{"type":"integer","maximum":500.0,"minimum":1.0},{"type":"null"}],"title":"Daily Send Limit","description":"Emails a day (1 to 500)."},"email_signature":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}],"title":"Email Signature","description":"HTML signature."},"warmup_enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Warmup Enabled","description":"`true` ramps the daily cap up over a few weeks; `false` sends the full limit."}},"additionalProperties":false,"type":"object","title":"MailboxUpdate","description":"Changes to a mailbox.","example":{"daily_send_limit":40,"warmup_enabled":true}},"Market":{"properties":{"object":{"type":"string","const":"market","title":"Object","description":"Always `market`.","default":"market"},"id":{"type":"string","title":"Id","description":"The market; a report's `market_id`, and a region config's `id` when scheduled."},"tracker_id":{"type":"string","title":"Tracker Id","description":"The tracker (the report's definition) it belongs to."},"name":{"type":"string","title":"Name","description":"Its label, else its place's name, its city or its country."},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Label"},"country":{"type":"string","title":"Country"},"city":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"City","description":"Null measures the whole country."},"region":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Region","description":"The city's state or province, when known."},"latitude":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Latitude","description":"The city's centre, when known (a linked place's own coordinates win on runs)."},"longitude":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Longitude"},"place_key":{"type":"string","title":"Place Key","description":"`country|city` lowercased: the `place` filter of the reader endpoints. `country|city|region` for a town of a name the country shares that is not the one the bare name is measured as (`australia|emerald|victoria` beside `australia|emerald`, which is Emerald, Queensland), so both can be measured."},"measured_as":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Measured As","description":"Set when the city has no `region` and the country has other towns of that name: the town it is measured as, e.g. `Emerald, Queensland`. Null otherwise."},"namesake_regions":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Namesake Regions","description":"With `measured_as`: the states or provinces of the country's other towns of that name. Set `region` on the market (`PATCH`) to measure one of them."},"location_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location Id","description":"The brand's place it measures, when linked."},"prompt_city_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prompt City Text","description":"What `{city}` becomes in its prompts; null uses `city`."},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language","description":"Null asks in the report's language."},"ai_platforms":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Ai Platforms","description":"Null asks the report's AI platforms."},"status":{"type":"string","enum":["active","paused","archived"],"title":"Status","description":"`paused` and `archived` markets are skipped by later runs."},"active_prompts_count":{"type":"integer","minimum":0.0,"title":"Active Prompts Count","description":"Active prompts it asks: the report's shared ones and its own."},"prompts_waiting_for_city":{"type":"integer","minimum":0.0,"title":"Prompts Waiting For City","description":"Of those, the ones that name `{city}` while the market has no city (no `city`, no `prompt_city_text` and a place without an address): they are not asked until it has one. A schedule whose every prompt waits is paused and resumes by itself.","default":0},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"additionalProperties":false,"type":"object","required":["id","tracker_id","name","country","place_key","status","active_prompts_count","created_at"],"title":"Market","description":"Where a report asks its prompts: a country or a city in it, optionally one of the brand's places.","example":{"active_prompts_count":12,"city":"Austin","country":"United States","created_at":"2026-10-20T10:00:00+00:00","id":"8a72d9f1-c4b5-4e6d-9b1f-0e3a2c6d8b04","latitude":30.2672,"location_id":"5c1e2f3a-4b5c-4d6e-8f70-112233445566","longitude":-97.7431,"name":"Austin","object":"market","place_key":"united states|austin","region":"Texas","status":"active","tracker_id":"8a72d9f1-c4b5-4e6d-9b1f-0e3a2c6d8b04"}},"MarketCreate":{"properties":{"markets":{"items":{"$ref":"#/components/schemas/MarketIn"},"type":"array","maxItems":250,"minItems":1,"title":"Markets"}},"additionalProperties":false,"type":"object","required":["markets"],"title":"MarketCreate","description":"Body for ``POST /v1/reports/{report_id}/markets``.","example":{"markets":[{"city":"Dallas","country":"United States"}]}},"MarketIn":{"properties":{"country":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Country","description":"Full English name; a place gives its own."},"city":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"City","description":"Null measures the whole country."},"region":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Region","description":"The city's state or province."},"latitude":{"anyOf":[{"type":"number","maximum":90.0,"minimum":-90.0},{"type":"null"}],"title":"Latitude","description":"The city's centre, with `longitude`; without them a city Google lists is placed on its own."},"longitude":{"anyOf":[{"type":"number","maximum":180.0,"minimum":-180.0},{"type":"null"}],"title":"Longitude"},"location_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location Id","description":"One of the brand's places (its city and country)."},"prompt_city_text":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Prompt City Text","description":"What `{city}` becomes."},"language":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"title":"Language","description":"Null asks in the report's language."},"ai_platforms":{"anyOf":[{"items":{"type":"string","enum":["chatgpt","claude","ai_overviews","grok","perplexity","gemini","muse"]},"type":"array","maxItems":10},{"type":"null"}],"title":"Ai Platforms","description":"Null asks the report's. Engines: `chatgpt`, `claude`, `ai_overviews`, `grok`, `perplexity`, `gemini`, `muse`. Each prompt costs 1 credit per 3 engines, rounded up: 1 to 3 engines cost 1 credit, 4 to 6 cost 2, all 7 cost 3. Any other value, retired ones included (`chatgpt_search`, `claude_search`), answers `ai_platform_unsupported`."},"label":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Label"}},"additionalProperties":false,"type":"object","title":"MarketIn","description":"A market to add: a country, a city in it, or one of the brand's places."},"MarketList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/Market"},"type":"array","title":"Data"}},"additionalProperties":false,"type":"object","required":["data"],"title":"MarketList","description":"A report's markets, oldest first."},"MarketUpdate":{"properties":{"status":{"anyOf":[{"type":"string","enum":["active","paused","archived"]},{"type":"null"}],"title":"Status"},"label":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Label"},"prompt_city_text":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Prompt City Text"},"location_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location Id"},"language":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"title":"Language"},"ai_platforms":{"anyOf":[{"items":{"type":"string","enum":["chatgpt","claude","ai_overviews","grok","perplexity","gemini","muse"]},"type":"array","maxItems":10},{"type":"null"}],"title":"Ai Platforms"},"region":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Region","description":"The city's state or province."},"latitude":{"anyOf":[{"type":"number","maximum":90.0,"minimum":-90.0},{"type":"null"}],"title":"Latitude","description":"The city's centre, with `longitude`."},"longitude":{"anyOf":[{"type":"number","maximum":180.0,"minimum":-180.0},{"type":"null"}],"title":"Longitude"}},"additionalProperties":false,"type":"object","title":"MarketUpdate","description":"Body for ``PATCH /v1/reports/{report_id}/markets/{market_id}``: the fields to change.","example":{"status":"paused"}},"MeResponse":{"properties":{"user_id":{"type":"string","title":"User Id","description":"Stable identifier for the authenticated principal (UUID)."},"auth_type":{"type":"string","enum":["api_key","jwt"],"title":"Auth Type","description":"Credential type used on this request: `api_key` (server-to-server) or `jwt` (a signed-in session)."},"plan":{"type":"string","title":"Plan","description":"The plan tier of the key creator's own subscription (`free`, `pro`, …). The monthly request pool and plan-gated account features follow `account_plan`, the plan of the account the key acts in."},"account_id":{"type":"string","title":"Account Id","description":"The account this key acts in: its creator's own (equal to `user_id`), or the team account that was active when the key was created. The key stops working if its creator leaves that account."},"account_role":{"type":"string","enum":["owner","editor","viewer"],"title":"Account Role","description":"The creator's role in that account: `owner` in their own, `editor` or `viewer` in a team account."},"account_plan":{"type":"string","title":"Account Plan","description":"Plan of the account this key acts in: equal to `plan` in the creator's own account, the owner's plan in a team account. It sizes the monthly request pool every key in that account draws on, and plan-gated account features follow it."},"key_prefix":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Key Prefix","description":"First 12 chars of the API key (e.g. `rp_live_abcd`). Only present when the key has the `read:meta` scope; null for JWT auth."},"scopes":{"anyOf":[{"items":{"type":"string","enum":["read:all","write:all","read:brands","write:brands","read:reports","write:reports","write:prompts","read:jobs","write:jobs","read:region-configs","write:region-configs","read:scheduled","write:scheduled","read:locations","write:locations","read:markets","write:markets","read:citations","write:citations","write:audit","read:webhooks","write:webhooks","read:meta","read:competitors","write:competitors","read:content","write:content","read:cms","write:cms","read:brand-audits","write:brand-audits","read:tasks","write:tasks","read:analytics","read:ads","read:seo","write:seo","read:outreach","write:outreach","read:community","write:community","read:gbp","write:gbp","read:merchant-center","read:youtube","read:client-reports","write:client-reports","read:agency","write:prospects","write:billing"]},"type":"array"},{"type":"null"}],"title":"Scopes","description":"Scopes granted to this key. Only present when the key has the `read:meta` scope."},"allowed_brand_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Allowed Brand Id","description":"If set, the key is restricted to this brand (UUID). Only present when the key has the `read:meta` scope; null for unrestricted keys."}},"additionalProperties":false,"type":"object","required":["user_id","auth_type","plan","account_id","account_role","account_plan"],"title":"MeResponse","description":"Identity envelope for ``GET /v1/me``.","example":{"account_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","account_plan":"pro","account_role":"owner","auth_type":"api_key","key_prefix":"rp_live_abcd","plan":"pro","scopes":["read:brands","write:brands"],"user_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04"}},"MerchantCenter":{"properties":{"object":{"type":"string","const":"merchant_center","title":"Object","default":"merchant_center"},"connected":{"type":"boolean","title":"Connected","description":"The brand has a live Google connection."},"expired":{"type":"boolean","title":"Expired","description":"The brand's Google connection lapsed: it is reconnected in the app.","default":false},"granted":{"type":"boolean","title":"Granted","description":"The connection's grant covers Merchant Center (the content scope)."},"account_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Account Id","description":"The Merchant Center account the products come from."},"account_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Account Name"},"synced_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Synced At","description":"When the products were last read from Google."},"health":{"anyOf":[{"$ref":"#/components/schemas/MerchantFeedHealth"},{"type":"null"}],"description":"Null until the products have been read once."}},"additionalProperties":false,"type":"object","required":["connected","granted","account_id","account_name","health"],"title":"MerchantCenter","description":"The brand's Merchant Center: whether Google grants it, the account it reads and the feed's health."},"MerchantFeedHealth":{"properties":{"total":{"type":"integer","title":"Total"},"approved":{"type":"integer","title":"Approved"},"disapproved":{"type":"integer","title":"Disapproved","description":"Disapproved by Google in at least one country."},"pending":{"type":"integer","title":"Pending","description":"Still under Google's review in at least one country."},"missing_gtin":{"type":"integer","title":"Missing Gtin","description":"No GTIN, leaving out the products the merchant says have none."},"missing_brand":{"type":"integer","title":"Missing Brand"},"price_mismatch":{"type":"integer","title":"Price Mismatch","description":"Google found another price on the landing page."},"out_of_stock":{"type":"integer","title":"Out Of Stock"},"top_issues":{"items":{"$ref":"#/components/schemas/MerchantIssueCount"},"type":"array","title":"Top Issues","description":"The five issues most products carry."}},"additionalProperties":false,"type":"object","required":["total","approved","disapproved","pending","missing_gtin","missing_brand","price_mismatch","out_of_stock","top_issues"],"title":"MerchantFeedHealth","example":{"approved":371,"disapproved":18,"missing_brand":2,"missing_gtin":9,"out_of_stock":31,"pending":23,"price_mismatch":6,"top_issues":[{"code":"price_mismatch","description":"Mismatched value (page crawl) [price]","kind":"price_mismatch","products":6}],"total":412}},"MerchantIssue":{"properties":{"code":{"type":"string","title":"Code"},"kind":{"type":"string","enum":["price_mismatch","missing_gtin","missing_brand","other"],"title":"Kind"},"severity":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Severity","description":"`NOT_IMPACTED`, `DEMOTED` or `DISAPPROVED`, as Google sends it."},"attribute":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Attribute"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detail"},"documentation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Documentation"}},"additionalProperties":false,"type":"object","required":["code","kind","severity","attribute","description","detail","documentation"],"title":"MerchantIssue"},"MerchantIssueCount":{"properties":{"code":{"type":"string","title":"Code","description":"Google's item level issue code."},"kind":{"type":"string","enum":["price_mismatch","missing_gtin","missing_brand","other"],"title":"Kind","description":"What the issue is about, read from its code and attribute."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Google's short English description of the issue."},"products":{"type":"integer","title":"Products","description":"How many products carry it."}},"additionalProperties":false,"type":"object","required":["code","kind","description","products"],"title":"MerchantIssueCount"},"MerchantProduct":{"properties":{"object":{"type":"string","const":"merchant_product","title":"Object","default":"merchant_product"},"product_name":{"type":"string","title":"Product Name","description":"Merchant API resource name, `accounts/{account}/products/{product}`."},"offer_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Offer Id"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"brand":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brand"},"price":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Price","description":"In units of `currency`."},"sale_price":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Sale Price"},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency"},"availability":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Availability","description":"Merchant API availability, such as `IN_STOCK` or `OUT_OF_STOCK`."},"link":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Link"},"image_link":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Link"},"gtins":{"items":{"type":"string"},"type":"array","title":"Gtins"},"product_types":{"items":{"type":"string"},"type":"array","title":"Product Types"},"google_product_category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Google Product Category"},"approval":{"type":"string","enum":["approved","disapproved","pending"],"title":"Approval"},"disapproved_countries":{"items":{"type":"string"},"type":"array","title":"Disapproved Countries"},"issues":{"items":{"$ref":"#/components/schemas/MerchantIssue"},"type":"array","title":"Issues"}},"additionalProperties":false,"type":"object","required":["product_name","offer_id","title","brand","price","sale_price","currency","availability","link","image_link","gtins","product_types","google_product_category","approval","disapproved_countries","issues"],"title":"MerchantProduct","example":{"approval":"approved","availability":"IN_STOCK","brand":"Vitamix","currency":"USD","disapproved_countries":[],"google_product_category":"Home & Garden > Kitchen & Dining > Kitchen Appliances > Food Mixers & Blenders","gtins":["703113640681"],"image_link":"https://www.vitamix.com/media/e310.jpg","issues":[],"link":"https://www.vitamix.com/us/en_us/shop/e310","object":"merchant_product","offer_id":"E310","price":349.95,"product_name":"accounts/123456789/products/en~US~E310","product_types":["Kitchen > Appliances > Blenders"],"title":"Vitamix E310 Explorian Blender - 48 oz Container"}},"MerchantProductPage":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/MerchantProduct"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"True when more items exist past this page. Fetch them with a larger `offset`."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of items matching the query, across all pages."},"limit":{"type":"integer","minimum":1.0,"title":"Limit","description":"Page size that was applied."},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of items skipped before this page."}},"additionalProperties":false,"type":"object","required":["data","has_more","total","limit","offset"],"title":"MerchantProductPage","description":"One page of products, with the total the view and search leave."},"MetricsRefreshed":{"properties":{"object":{"type":"string","const":"keyword_metrics_refreshed","title":"Object","default":"keyword_metrics_refreshed"},"refreshed":{"type":"integer","title":"Refreshed"},"skipped_fresh":{"type":"integer","title":"Skipped Fresh","description":"Keywords whose numbers are less than a day old, left out."},"credits_charged":{"type":"integer","title":"Credits Charged"}},"type":"object","required":["refreshed","skipped_fresh","credits_charged"],"title":"MetricsRefreshed"},"MonthlySearches":{"properties":{"year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Year"},"month":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Month"},"search_volume":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Search Volume","description":"Null for a month the provider has no data for."}},"type":"object","title":"MonthlySearches"},"NextDirectoryCheck":{"properties":{"directories":{"type":"integer","title":"Directories","description":"Directories a check would search now."},"credits":{"type":"integer","title":"Credits","description":"Credits it would cost."}},"additionalProperties":false,"type":"object","required":["directories","credits"],"title":"NextDirectoryCheck","description":"What a check would search and cost now."},"OffsiteKind":{"properties":{"object":{"type":"string","const":"offsite_kind","title":"Object","description":"Always `offsite_kind`.","default":"offsite_kind"},"source_type":{"type":"string","title":"Source Type","description":"`owned` (the brand's own site), `competitor` (a registered competitor's), else the kind of site (an open set, e.g. `reddit`, `news`, `reviews`), or `classifying` while unknown."},"pages":{"type":"integer","minimum":0.0,"title":"Pages","description":"Cited pages of this kind."},"analyzed":{"type":"integer","minimum":0.0,"title":"Analyzed","description":"Of them, pages a page analysis read."},"named":{"items":{"$ref":"#/components/schemas/OffsiteNamed"},"type":"array","title":"Named","description":"Who the analyzed pages name."}},"additionalProperties":false,"type":"object","required":["source_type","pages","analyzed","named"],"title":"OffsiteKind","description":"One kind of third-party site: its cited pages, how many were analyzed, and who they name."},"OffsiteMention":{"properties":{"competitor_id":{"type":"string","title":"Competitor Id"},"name":{"type":"string","title":"Name"},"sentence":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sentence","description":"The sentence that names it."},"sentiment":{"anyOf":[{"type":"string","enum":["positive","neutral","negative"]},{"type":"null"}],"title":"Sentiment"},"prominence":{"anyOf":[{"type":"string","enum":["headline","body","sidebar","footnote","comparison"]},{"type":"null"}],"title":"Prominence","description":"`headline`, `body`, `sidebar`, `footnote` or `comparison`."}},"additionalProperties":false,"type":"object","required":["competitor_id","name"],"title":"OffsiteMention","description":"A competitor an analyzed page names."},"OffsiteNamed":{"properties":{"competitor_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Competitor Id","description":"The competitor; `null` for the brand itself."},"is_brand":{"type":"boolean","title":"Is Brand","description":"True for the brand itself."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Its name."},"pages":{"type":"integer","minimum":0.0,"title":"Pages","description":"Analyzed pages that name it."},"positive":{"type":"integer","minimum":0.0,"title":"Positive"},"neutral":{"type":"integer","minimum":0.0,"title":"Neutral"},"negative":{"type":"integer","minimum":0.0,"title":"Negative"}},"additionalProperties":false,"type":"object","required":["is_brand","pages","positive","neutral","negative"],"title":"OffsiteNamed","description":"The brand or one competitor, and the analyzed pages of a kind that name it."},"OffsitePage":{"properties":{"object":{"type":"string","const":"offsite_page","title":"Object","description":"Always `offsite_page`.","default":"offsite_page"},"url":{"type":"string","title":"Url"},"domain":{"type":"string","title":"Domain"},"source_type":{"type":"string","title":"Source Type","description":"`owned` (the brand's own site), `competitor` (a registered competitor's), else the kind of site (an open set, e.g. `reddit`, `news`, `reviews`), or `classifying` while unknown."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"citations":{"type":"integer","minimum":0.0,"title":"Citations","description":"Times the answers cited it under the filters."},"prompt_count":{"type":"integer","minimum":0.0,"title":"Prompt Count"},"platforms":{"items":{"type":"string"},"type":"array","title":"Platforms","description":"Engines that cited it (an open set)."},"last_seen":{"type":"string","format":"date-time","title":"Last Seen"},"page_category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Page Category"},"analyzed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"format":"date-time","title":"Analyzed At","description":"When a page analysis read it; `null` until then."},"brand_mentioned":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Brand Mentioned","description":"Whether it names the brand; `null` until analyzed."},"brand_sentiment":{"anyOf":[{"type":"string","enum":["positive","neutral","negative"]},{"type":"null"}],"title":"Brand Sentiment"},"brand_context":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brand Context","description":"What it says about the brand."},"page_mentions":{"anyOf":[{"items":{"$ref":"#/components/schemas/OffsiteMention"},"type":"array"},{"type":"null"}],"title":"Page Mentions","description":"Competitors it names, most prominent first; `null` until analyzed."},"has_backlink":{"type":"boolean","title":"Has Backlink","description":"Whether it links to the brand's site."},"outreach_stage":{"anyOf":[{"type":"string","enum":["contact_found","contacted","replied","won"]},{"type":"null"}],"title":"Outreach Stage","description":"`contact_found`, `contacted`, `replied` or `won`, when outreach started."},"audit_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Audit Id","description":"The latest brand audit that cited the page."}},"additionalProperties":false,"type":"object","required":["url","domain","source_type","citations","prompt_count","platforms","last_seen","has_backlink"],"title":"OffsitePage","description":"A third-party page the answers or a brand audit cited, as a page analysis read it."},"OffsitePageList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/OffsitePage"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"True when more items exist past this page. Fetch them with a larger `offset`."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of items matching the query, across all pages."},"limit":{"type":"integer","minimum":1.0,"title":"Limit","description":"Page size that was applied."},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of items skipped before this page."}},"additionalProperties":false,"type":"object","required":["data","has_more","total","limit","offset"],"title":"OffsitePageList","description":"A page of off-site pages."},"OffsiteSummary":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/OffsiteKind"},"type":"array","title":"Data"}},"additionalProperties":false,"type":"object","required":["data"],"title":"OffsiteSummary","description":"The off-site summary, one row per kind of site."},"OutreachAnalysisCreate":{"properties":{"urls":{"items":{"type":"string"},"type":"array","maxItems":30,"minItems":1,"title":"Urls","description":"Public page URLs (1 to 30). One credit per three pages; pages already analyzed with their contacts settled are left out before pricing."}},"additionalProperties":false,"type":"object","required":["urls"],"title":"OutreachAnalysisCreate","description":"Cited pages to analyze for outreach.","example":{"urls":["https://www.runnersworld.com/gear/a20865766/best-running-shoes/"]}},"OutreachAnalysisDispatched":{"properties":{"object":{"type":"string","const":"outreach_analysis","title":"Object","default":"outreach_analysis"},"job_id":{"type":"string","title":"Job Id","description":"Poll `GET /v1/jobs/{job_id}` until it is `completed`."},"pages":{"type":"integer","minimum":1.0,"title":"Pages","description":"Pages sent to the analysis."}},"additionalProperties":false,"type":"object","required":["job_id","pages"],"title":"OutreachAnalysisDispatched","description":"The analysis job that was queued.","example":{"job_id":"5d6e7f80-1a2b-4c3d-8e9f-0a1b2c3d4e5f","object":"outreach_analysis","pages":3}},"OutreachAuthor":{"properties":{"object":{"type":"string","const":"outreach_author","title":"Object","default":"outreach_author"},"contact_id":{"type":"string","title":"Contact Id","description":"The author's contact id."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Name."},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email","description":"Email address."},"company":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company","description":"Company."},"linkedin_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Linkedin Url","description":"LinkedIn profile."},"page_count":{"type":"integer","minimum":0.0,"title":"Page Count","description":"Cited pages they wrote."},"total_citations":{"type":"integer","minimum":0.0,"title":"Total Citations","description":"Times the answers cited those pages under the filters."},"domains":{"items":{"type":"string"},"type":"array","title":"Domains","description":"Sites those pages are on."},"prompt_count":{"type":"integer","minimum":0.0,"title":"Prompt Count","description":"Distinct prompts whose answers cited them.","default":0},"last_seen":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"format":"date-time","title":"Last Seen","description":"Last time an answer cited one of them."}},"additionalProperties":false,"type":"object","required":["contact_id","page_count","total_citations"],"title":"OutreachAuthor","description":"A page author with a contact, summed over the pages they wrote that the answers cite under the filters."},"OutreachAuthorList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/OutreachAuthor"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"True when more items exist past this page. Fetch them with a larger `offset`."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of items matching the query, across all pages."},"limit":{"type":"integer","minimum":1.0,"title":"Limit","description":"Page size that was applied."},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of items skipped before this page."}},"additionalProperties":false,"type":"object","required":["data","has_more","total","limit","offset"],"title":"OutreachAuthorList","description":"A page of authors, most cited first.","example":{"data":[{"company":"Forbes","contact_id":"7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d","domains":["forbes.com"],"email":"alex.rivera@e2e.test","last_seen":"2026-10-01T12:00:00Z","name":"Alex Rivera","object":"outreach_author","page_count":4,"prompt_count":9,"total_citations":37}],"has_more":false,"limit":20,"object":"list","offset":0,"total":1}},"OutreachContactRef":{"properties":{"id":{"type":"string","title":"Id","description":"Contact id; `GET /v1/brands/{brand_id}/contacts/{contact_id}` reads it."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Name."},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email","description":"Email address."}},"additionalProperties":false,"type":"object","required":["id"],"title":"OutreachContactRef","description":"A contact named by id with the fields that identify it."},"OutreachPageContact":{"properties":{"object":{"type":"string","const":"outreach_page_contact","title":"Object","default":"outreach_page_contact"},"citation_id":{"type":"string","title":"Citation Id","description":"The cited page's id, as `GET /v1/brands/{brand_id}/citations` lists it."},"url":{"type":"string","title":"Url","description":"The page URL."},"contact":{"anyOf":[{"$ref":"#/components/schemas/OutreachContactRef"},{"type":"null"}],"description":"The page's primary contact."}},"additionalProperties":false,"type":"object","required":["citation_id","url"],"title":"OutreachPageContact","description":"A cited page with the primary contact it now has.","example":{"citation_id":"3c1f5a7e-8b2d-4e6f-9a0b-1c2d3e4f5a6b","contact":{"email":"alex.rivera@e2e.test","id":"7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d","name":"Alex Rivera"},"object":"outreach_page_contact","url":"https://www.runnersworld.com/gear/a20865766/best-running-shoes/"}},"OutreachPageContactUpdate":{"properties":{"author_name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Author Name","description":"The page author's name."},"author_email":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Author Email","description":"The page author's email."}},"additionalProperties":false,"type":"object","title":"OutreachPageContactUpdate","description":"The contact found by hand for a cited page.","example":{"author_email":"alex.rivera@e2e.test","author_name":"Alex Rivera"}},"ProspectOutreachPreview":{"properties":{"object":{"type":"string","const":"prospect.outreach_preview","title":"Object","default":"prospect.outreach_preview"},"prospect_id":{"type":"string","title":"Prospect Id"},"ready":{"type":"boolean","title":"Ready","description":"Whether it can be sent as it stands."},"not_ready_reasons":{"items":{"type":"string"},"type":"array","title":"Not Ready Reasons","description":"`no_contact_email`, `report_running`, `nothing_to_send`, `empty_subject` or `empty_body`. The set is open."},"emails":{"items":{"$ref":"#/components/schemas/ProspectOutreachPreviewEmail"},"type":"array","title":"Emails"},"variables":{"items":{"$ref":"#/components/schemas/ProspectOutreachVariable"},"type":"array","title":"Variables"}},"additionalProperties":false,"type":"object","required":["prospect_id","ready"],"title":"ProspectOutreachPreview","description":"A prospect's outreach as it would go out, with real values, and whether it is ready to send."},"ProspectOutreachPreviewEmail":{"properties":{"step_id":{"type":"string","title":"Step Id"},"is_pitch":{"type":"boolean","title":"Is Pitch","description":"The prospect's own pitch, sent first.","default":false},"wait_days_before":{"type":"integer","title":"Wait Days Before","default":0},"subject":{"$ref":"#/components/schemas/ProspectOutreachRenderedText"},"body":{"$ref":"#/components/schemas/ProspectOutreachRenderedText"}},"additionalProperties":false,"type":"object","required":["step_id","subject","body"],"title":"ProspectOutreachPreviewEmail","description":"One email of the outreach, rendered for this prospect."},"ProspectOutreachRenderedText":{"properties":{"text":{"type":"string","title":"Text","description":"What goes out."},"segments":{"items":{"$ref":"#/components/schemas/ProspectOutreachSegment"},"type":"array","title":"Segments"},"missing":{"items":{"type":"string"},"type":"array","title":"Missing","description":"Variables with no value."},"dropped":{"type":"integer","title":"Dropped","description":"Sentences left out.","default":0}},"additionalProperties":false,"type":"object","required":["text"],"title":"ProspectOutreachRenderedText","description":"An email's subject or body as it would be sent."},"ProspectOutreachSegment":{"properties":{"text":{"type":"string","title":"Text"},"kind":{"type":"string","enum":["text","value","fallback","dropped"],"title":"Kind","description":"`text` as written, `value` a variable's real value, `fallback` the text a missing variable falls back to, `dropped` a sentence left out because a variable it needs has no value (never sent).","default":"text"},"variable":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Variable"},"missing":{"items":{"type":"string"},"type":"array","title":"Missing","description":"For `dropped`: the variables with no value."}},"additionalProperties":false,"type":"object","required":["text"],"title":"ProspectOutreachSegment","description":"A piece of a rendered email."},"OutreachTargetsAdded":{"properties":{"object":{"type":"string","const":"outreach_targets_added","title":"Object","default":"outreach_targets_added"},"added":{"type":"integer","minimum":0.0,"title":"Added","description":"Pages added; each is categorized on its own a few minutes later, free."},"skipped":{"type":"integer","minimum":0.0,"title":"Skipped","description":"Pages that were already in Backlink outreach."}},"additionalProperties":false,"type":"object","required":["added","skipped"],"title":"OutreachTargetsAdded","description":"How many pages were added and how many were already there.","example":{"added":1,"object":"outreach_targets_added","skipped":0}},"OutreachTargetsCreate":{"properties":{"urls":{"items":{"type":"string"},"type":"array","maxItems":200,"minItems":1,"title":"Urls","description":"Public page URLs (1 to 200). Pages already in Backlink outreach are skipped."}},"additionalProperties":false,"type":"object","required":["urls"],"title":"OutreachTargetsCreate","description":"Pages to add to Backlink outreach.","example":{"urls":["https://www.runnersworld.com/gear/a20865766/best-running-shoes/"]}},"ProspectOutreachVariable":{"properties":{"name":{"type":"string","title":"Name"},"value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Value"},"state":{"type":"string","enum":["filled","fallback","missing"],"title":"State"}},"additionalProperties":false,"type":"object","required":["name","state"],"title":"ProspectOutreachVariable","description":"A variable the emails use."},"OwnVideo":{"properties":{"video_id":{"type":"string","title":"Video Id"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"published_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Published At"},"view_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"View Count"},"duration_seconds":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Duration Seconds"},"thumbnail_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Thumbnail Url"},"has_captions":{"type":"boolean","title":"Has Captions","description":"The video has captions, which the engines read as its transcript."},"chapters":{"type":"integer","title":"Chapters","description":"How many chapters YouTube shows; 0 when the description makes none."},"citations":{"type":"integer","title":"Citations","description":"Distinct AI answers that cited the video in the last 90 days."},"platforms":{"items":{"type":"string"},"type":"array","title":"Platforms"}},"additionalProperties":false,"type":"object","required":["video_id","title","view_count","duration_seconds","thumbnail_url","has_captions","chapters","citations","platforms"],"title":"OwnVideo"},"PageAuditItem":{"properties":{"url":{"type":"string","title":"Url","description":"The requested URL."},"ok":{"type":"boolean","title":"Ok","description":"True when the page was audited; false when it could not be (and is not charged)."},"final_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Final Url","description":"The final URL after redirects (when audited)."},"score":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Score","description":"Best-practice score (share of checks passed)."},"passed":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Passed","description":"True when the score clears the pass threshold (70) and no finding is critical."},"checks_passed":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Checks Passed"},"checks_total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Checks Total"},"recommendations":{"items":{"$ref":"#/components/schemas/PageAuditRecommendation"},"type":"array","title":"Recommendations","description":"Concrete fixes, ordered by severity (critical first)."},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Why the page could not be audited (when ok is false)."}},"additionalProperties":false,"type":"object","required":["url","ok"],"title":"PageAuditItem","description":"One page's outcome: the audit fields when ok, or an error when it could not be fetched."},"PageAuditRecommendation":{"properties":{"category":{"type":"string","enum":["meta","headings","structured_data","social","indexability","aeo","security"],"title":"Category","description":"Which area of SEO/AEO the finding belongs to."},"severity":{"type":"string","enum":["critical","warning","info"],"title":"Severity","description":"How impactful the issue is."},"message":{"type":"string","title":"Message","description":"Human-readable, actionable fix."}},"additionalProperties":false,"type":"object","required":["category","severity","message"],"title":"PageAuditRecommendation","description":"One concrete, actionable SEO/AEO finding.","example":{"category":"meta","message":"Title is 18 characters; aim for 50-60 so it is not truncated in search results.","severity":"warning"}},"PageAuditRequest":{"properties":{"url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Url","description":"A single public https page URL to audit.","examples":["https://rankprompt.com/pricing"]},"urls":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Urls","description":"Several public https page URLs to audit (1 credit each).","examples":[["https://rankprompt.com","https://rankprompt.com/pricing"]]},"sitemap":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Sitemap","description":"A sitemap.xml URL (or a bare domain, resolved to /sitemap.xml) whose first pages are audited. Domain-level checks (robots.txt, sitemap, /llms.txt, SSL) run once and are reused across pages."},"limit":{"type":"integer","maximum":20.0,"minimum":1.0,"title":"Limit","description":"Max pages to audit (cap when expanding a sitemap, and the hard ceiling for `urls`).","default":10},"request_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Request Id","description":"Optional id, unique per intended billable audit, combined with each URL to make a retried per-URL charge idempotent. Omit it and every call is charged."}},"additionalProperties":false,"type":"object","title":"PageAuditRequest","description":"Request body for ``POST /v1/page-audit``. Provide exactly one of url / urls / sitemap.","example":{"request_id":"ci-run-918273","urls":["https://rankprompt.com","https://rankprompt.com/pricing"]}},"PageAuditResult":{"properties":{"object":{"type":"string","const":"page_audit","title":"Object","default":"page_audit"},"results":{"items":{"$ref":"#/components/schemas/PageAuditItem"},"type":"array","title":"Results","description":"Per-URL outcomes, in request order."},"credits_charged":{"type":"integer","minimum":0.0,"title":"Credits Charged","description":"Credits actually spent (one per successfully audited page)."},"truncated":{"type":"boolean","title":"Truncated","description":"True when more URLs were supplied (or found in the sitemap) than were audited because of `limit` or the batch cap; `results` holds the first ones in request order.","default":false},"skipped_urls":{"type":"integer","minimum":0.0,"title":"Skipped Urls","description":"How many supplied URLs were not audited.","default":0}},"additionalProperties":false,"type":"object","required":["results","credits_charged"],"title":"PageAuditResult","description":"Response body for ``POST /v1/page-audit``.","example":{"credits_charged":1,"object":"page_audit","results":[{"checks_passed":9,"checks_total":11,"final_url":"https://rankprompt.com/pricing","ok":true,"passed":true,"recommendations":[{"category":"meta","message":"Title is 18 characters; aim for 50-60 so it is not truncated in search results.","severity":"warning"}],"score":82,"url":"https://rankprompt.com/pricing"}]}},"PagePerformance":{"properties":{"object":{"type":"string","const":"page_performance","title":"Object","default":"page_performance"},"path":{"type":"string","title":"Path","description":"The page path the numbers are for."},"sessions":{"type":"integer","minimum":0.0,"title":"Sessions","default":0},"users":{"type":"integer","minimum":0.0,"title":"Users","default":0},"page_views":{"type":"integer","minimum":0.0,"title":"Page Views","default":0},"avg_session_duration":{"type":"number","title":"Avg Session Duration","description":"Average session length, in seconds.","default":0.0},"engagement_rate":{"type":"number","title":"Engagement Rate","description":"GA4 engagement rate, as a percentage.","default":0.0},"clicks":{"type":"integer","minimum":0.0,"title":"Clicks","default":0},"impressions":{"type":"integer","minimum":0.0,"title":"Impressions","default":0},"ctr":{"type":"number","title":"Ctr","description":"Clicks over impressions, as a percentage.","default":0.0},"position":{"type":"number","title":"Position","default":0.0},"queries":{"items":{"$ref":"#/components/schemas/SearchRow"},"type":"array","title":"Queries","description":"Queries that led to this page."},"date_range_start":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Date Range Start"},"date_range_end":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Date Range End"}},"additionalProperties":false,"type":"object","required":["path"],"title":"PagePerformance","description":"What one page earned in Google: GA4 behaviour plus its Search Console numbers and queries."},"PeopleAlsoAsk":{"properties":{"question":{"type":"string","title":"Question","description":"A question Google listed under People also ask, as written."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"Where Google took the answer from, when the page showed it."},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain","description":"The domain of `url`."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"The title of the page at `url`, as Google showed it."}},"type":"object","required":["question"],"title":"PeopleAlsoAsk"},"PlaceDirectories":{"properties":{"object":{"type":"string","const":"place_directories","title":"Object","description":"Always `place_directories`.","default":"place_directories"},"location_id":{"type":"string","title":"Location Id"},"categories":{"items":{"type":"string","enum":["general","legal","health","home","hospitality"]},"type":"array","title":"Categories","description":"The place's kinds of business, `general` always."},"data":{"items":{"$ref":"#/components/schemas/DirectoryListing"},"type":"array","title":"Data"},"check":{"anyOf":[{"$ref":"#/components/schemas/DirectoryCheck"},{"type":"null"}],"description":"The latest check, if any."},"next_check":{"$ref":"#/components/schemas/NextDirectoryCheck"}},"additionalProperties":false,"type":"object","required":["location_id","categories","data","next_check"],"title":"PlaceDirectories","description":"A place's local sources: its directories, its presence on each, the latest check and the next one's cost."},"PlaceGeoScan":{"properties":{"object":{"type":"string","const":"geo_scan","title":"Object","description":"Always `geo_scan`.","default":"geo_scan"},"id":{"type":"string","title":"Id"},"location_id":{"type":"string","title":"Location Id","description":"The place the grid is centred on."},"gbp_location_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gbp Location Id","description":"The Google location the place is linked to; null when it is not linked."},"schedule_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Schedule Id","description":"The schedule that ran it; null for a scan by hand."},"run_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run Id","description":"Scans started together share it."},"keyword":{"type":"string","title":"Keyword"},"grid_size":{"type":"integer","title":"Grid Size"},"point_count":{"type":"integer","title":"Point Count"},"spacing_km":{"type":"number","title":"Spacing Km"},"center_lat":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Center Lat"},"center_lng":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Center Lng"},"status":{"type":"string","enum":["pending","running","completed","failed"],"title":"Status","description":"`pending`, `running`, `completed` or `failed`."},"avg_rank":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Rank","description":"Mean rank over the points it ranked at, once completed."},"found_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Found Count","description":"Points where it is in the local pack, once completed."},"top3_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Top3 Count","description":"Points where it ranked 1 to 3, once completed."},"last_error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Error Message"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completed At"},"points":{"items":{"$ref":"#/components/schemas/GeoScanPoint"},"type":"array","title":"Points"}},"additionalProperties":false,"type":"object","required":["id","location_id","keyword","grid_size","point_count","spacing_km","status"],"title":"PlaceGeoScan","description":"A scan of a place with every point of its grid."},"PlaceGeoScanCreate":{"properties":{"grid_size":{"type":"integer","title":"Grid Size","description":"N in the NxN grid (3, 5 or 7)","default":3},"spacing_km":{"anyOf":[{"type":"number","maximum":20.0,"exclusiveMinimum":0.0},{"type":"string","const":"auto"}],"title":"Spacing Km","description":"Distance between adjacent grid points, km, or \"auto\": the centre is read first and the spacing set off how far its results lie (0.4 of their median distance, at least 1 km when fewer than 10 come back, rounded to 0.1, 0.2, 0.3, 0.5, 1, 1.5, 2 or 5 km). Left out, it is auto.","default":"auto"},"center_lat":{"anyOf":[{"type":"number","maximum":90.0,"minimum":-90.0},{"type":"null"}],"title":"Center Lat","description":"The grid's centre; null uses the place's pin"},"center_lng":{"anyOf":[{"type":"number","maximum":180.0,"minimum":-180.0},{"type":"null"}],"title":"Center Lng"},"keywords":{"items":{"type":"string"},"type":"array","maxItems":10,"minItems":1,"title":"Keywords"}},"additionalProperties":false,"type":"object","required":["keywords"],"title":"PlaceGeoScanCreate","description":"Scan the place now for each search: one scan per search, every one on the same grid.","example":{"grid_size":5,"keywords":["dentist","emergency dentist"],"spacing_km":1.5}},"PlaceGeoScanList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/PlaceGeoScanSummary"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Opaque continuation token. Pass back as `?cursor=` to fetch the next page. `null` when `has_more` is false."}},"additionalProperties":false,"type":"object","required":["data","has_more"],"title":"PlaceGeoScanList","description":"A page of a place's scans, newest first."},"PlaceGeoScanRun":{"properties":{"object":{"type":"string","const":"geo_scan_run","title":"Object","description":"Always `geo_scan_run`.","default":"geo_scan_run"},"run_id":{"type":"string","title":"Run Id"},"data":{"items":{"$ref":"#/components/schemas/PlaceGeoScanSummary"},"type":"array","title":"Data"},"ai_scan":{"anyOf":[{"$ref":"#/components/schemas/AiGeoScanSummary"},{"type":"null"}],"description":"The run's AI grid, when it asked questions (a schedule with `prompts`)."}},"additionalProperties":false,"type":"object","required":["run_id","data"],"title":"PlaceGeoScanRun","description":"The pending scans one request started."},"PlaceGeoScanSummary":{"properties":{"object":{"type":"string","const":"geo_scan","title":"Object","description":"Always `geo_scan`.","default":"geo_scan"},"id":{"type":"string","title":"Id"},"location_id":{"type":"string","title":"Location Id","description":"The place the grid is centred on."},"gbp_location_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gbp Location Id","description":"The Google location the place is linked to; null when it is not linked."},"schedule_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Schedule Id","description":"The schedule that ran it; null for a scan by hand."},"run_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run Id","description":"Scans started together share it."},"keyword":{"type":"string","title":"Keyword"},"grid_size":{"type":"integer","title":"Grid Size"},"point_count":{"type":"integer","title":"Point Count"},"spacing_km":{"type":"number","title":"Spacing Km"},"center_lat":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Center Lat"},"center_lng":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Center Lng"},"status":{"type":"string","enum":["pending","running","completed","failed"],"title":"Status","description":"`pending`, `running`, `completed` or `failed`."},"avg_rank":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Rank","description":"Mean rank over the points it ranked at, once completed."},"found_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Found Count","description":"Points where it is in the local pack, once completed."},"top3_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Top3 Count","description":"Points where it ranked 1 to 3, once completed."},"last_error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Error Message"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completed At"}},"additionalProperties":false,"type":"object","required":["id","location_id","keyword","grid_size","point_count","spacing_km","status"],"title":"PlaceGeoScanSummary","description":"A scan of a place without its points."},"Portfolio":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/PortfolioBrand"},"type":"array","title":"Data"}},"additionalProperties":false,"type":"object","required":["data"],"title":"Portfolio","description":"One row per brand the key reaches."},"PortfolioBrand":{"properties":{"object":{"type":"string","const":"portfolio_brand","title":"Object","default":"portfolio_brand"},"brand_id":{"type":"string","title":"Brand Id"},"brand_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brand Name"},"website":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Website"},"client_company":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Client Company"},"client_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Client Name"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags"},"latest_visibility_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Latest Visibility Score"},"avg_visibility_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Visibility Score"},"prev_period_visibility_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Prev Period Visibility Score","description":"The score of the period before."},"visibility_series":{"items":{"type":"number"},"type":"array","title":"Visibility Series","description":"The scores of the recent runs, oldest first."},"trend_direction":{"type":"string","title":"Trend Direction","description":"`up`, `down` or `stable`."},"reports_count":{"type":"integer","title":"Reports Count","default":0},"completed_reports_count":{"type":"integer","title":"Completed Reports Count","default":0},"credits_used":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Credits Used"},"last_report_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Report Date","description":"The newest report within the window."},"last_completed_report_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Completed Report At","description":"The newest completed report of any age; set when `last_report_date` is null because every report is older than the window."},"next_scheduled_run":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Scheduled Run"},"schedule_cadence":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Schedule Cadence"},"last_delivery_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Delivery Status"},"pending_reviews_count":{"type":"integer","title":"Pending Reviews Count","default":0},"unresolved_comments_count":{"type":"integer","title":"Unresolved Comments Count","default":0},"open_board_cards_count":{"type":"integer","title":"Open Board Cards Count","default":0},"active_shares_count":{"type":"integer","title":"Active Shares Count","default":0},"engines_asked":{"items":{"type":"string"},"type":"array","title":"Engines Asked","description":"The engines the brand's newest completed report asked."},"engines_naming":{"items":{"type":"string"},"type":"array","title":"Engines Naming","description":"The engines among them whose answers named the brand."}},"additionalProperties":false,"type":"object","required":["brand_id","trend_direction"],"title":"PortfolioBrand","description":"One brand's row in the portfolio."},"PortfolioCompetitor":{"properties":{"object":{"type":"string","const":"portfolio_competitor","title":"Object","default":"portfolio_competitor"},"name":{"type":"string","title":"Name"},"total_mentions":{"type":"integer","title":"Total Mentions"},"brands_count":{"type":"integer","title":"Brands Count","description":"Brands whose answers named it."},"brand_ids":{"items":{"type":"string"},"type":"array","title":"Brand Ids"},"website":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Website"},"first_seen":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"First Seen"},"platforms":{"items":{"type":"string"},"type":"array","title":"Platforms"}},"additionalProperties":false,"type":"object","required":["name","total_mentions","brands_count","brand_ids"],"title":"PortfolioCompetitor","description":"A competitor across the portfolio's recent reports."},"PortfolioCompetitorList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/PortfolioCompetitor"},"type":"array","title":"Data"}},"additionalProperties":false,"type":"object","required":["data"],"title":"PortfolioCompetitorList","description":"The portfolio's competitor leaderboard, most mentioned first."},"ProductMention":{"properties":{"object":{"type":"string","const":"product_mention","title":"Object","default":"product_mention"},"product_name":{"type":"string","title":"Product Name"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"answers":{"type":"integer","title":"Answers","description":"Answers of the run that named the product."},"platforms":{"items":{"type":"string"},"type":"array","title":"Platforms","description":"The AI platforms whose answers named it."},"prompts":{"items":{"type":"string"},"type":"array","title":"Prompts","description":"Up to five prompts whose answers named it."}},"additionalProperties":false,"type":"object","required":["product_name","title","answers","platforms","prompts"],"title":"ProductMention"},"ProductMentionList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/ProductMention"},"type":"array","title":"Data"},"report_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Report Id","description":"The run read: the one asked for, or the brand's latest completed one."},"answers":{"type":"integer","title":"Answers","description":"Answers the run holds."}},"additionalProperties":false,"type":"object","required":["data","report_id","answers"],"title":"ProductMentionList"},"ProductPrompt":{"properties":{"object":{"type":"string","const":"product_prompt","title":"Object","default":"product_prompt"},"prompt":{"type":"string","title":"Prompt","description":"A shopping prompt in the brand's market language, ready to track in a report."},"category":{"type":"string","title":"Category"},"products":{"items":{"type":"string"},"type":"array","title":"Products","description":"Up to three product titles that would answer it."}},"additionalProperties":false,"type":"object","required":["prompt","category","products"],"title":"ProductPrompt"},"ProductPromptList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/ProductPrompt"},"type":"array","title":"Data"}},"additionalProperties":false,"type":"object","required":["data"],"title":"ProductPromptList","description":"The shopping prompts the catalog suggests."},"Prompt":{"properties":{"object":{"type":"string","title":"Object","description":"Always `prompt`.","default":"prompt"},"id":{"type":"string","title":"Id","description":"Stable prompt identifier (UUID)."},"brand_id":{"type":"string","title":"Brand Id","description":"Owning brand id (UUID)."},"report_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Report Id","description":"Report this prompt belongs to."},"prompt_text":{"type":"string","title":"Prompt Text","description":"The natural-language query sent to the AI platforms."},"category":{"type":"string","title":"Category","description":"Free-form taxonomy bucket. Used to group prompts in analytics surfaces."},"intent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Intent","description":"The prompt's funnel intent: `awareness` (learning about a topic), `consideration` (weighing options) or `decision` (choosing between named options); `null` when unclassified. Written with generated prompts, set by hand otherwise. An open set."},"region_config_prompt_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Region Config Prompt Id","description":"The tracked prompt this prompt was asked from, the same id in every run and market that asks it (a region config prompt's id for a scheduled report). Null only for prompts older than tracking."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"ISO-8601 timestamp when the prompt was created."}},"additionalProperties":false,"type":"object","required":["id","brand_id","prompt_text","category","created_at"],"title":"Prompt","description":"A prompt that drives a report.","example":{"brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","category":"Running Shoes","created_at":"2026-04-01T11:00:00+00:00","id":"018e7c2c-33ab-7df1-b1cd-2ac3a8f9112d","intent":"consideration","object":"prompt","prompt_text":"What are the best running shoes for a first marathon?","report_id":"8a72d9f1-c4b5-4e6d-9b1f-0e3a2c6d8b04"}},"PromptAnswer":{"properties":{"object":{"type":"string","const":"prompt_answer","title":"Object","description":"Always `prompt_answer`.","default":"prompt_answer"},"id":{"type":"string","title":"Id","description":"The answer id; read it in full with `GET .../prompts/answers/{answer_id}`."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the engine answered."},"platform":{"type":"string","title":"Platform","description":"The engine that answered (an open set, e.g. `chatgpt`, `gemini`)."},"model_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model Version","description":"Model that answered, when it was recorded."},"prompt_text":{"type":"string","title":"Prompt Text","description":"The prompt as sent to the engine."},"prompt_hash":{"type":"string","title":"Prompt Hash","description":"Stable id of the text, the `prompt_hash` of the prompt rows."},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category","description":"The prompt's category."},"brand_appears":{"type":"boolean","title":"Brand Appears","description":"True when the answer names the brand."},"rank":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Rank","description":"The brand's position in the answer."},"brands_named":{"items":{"$ref":"#/components/schemas/PromptAnswerBrand"},"type":"array","title":"Brands Named","description":"Brands the answer names, in its order, a registered competitor under its canonical name."},"citation_count":{"type":"integer","minimum":0.0,"title":"Citation Count","description":"Distinct URLs the answer cites."},"report_id":{"type":"string","title":"Report Id","description":"The report whose run produced the answer."},"report_name":{"type":"string","title":"Report Name","description":"Name of that report."}},"additionalProperties":false,"type":"object","required":["id","created_at","platform","prompt_text","prompt_hash","brand_appears","brands_named","citation_count","report_id","report_name"],"title":"PromptAnswer","description":"One engine answer to one run of a brand prompt, without its text.","example":{"brand_appears":true,"brands_named":[{"category":"my_brand","name":"adidas"},{"category":"direct_competitor","name":"Nike"}],"category":"Marathon","citation_count":6,"created_at":"2026-09-20T08:15:00Z","id":"3c9e2f4a-1b2d-4e5f-8a6b-7c8d9e0f1a2b","model_version":"gpt-6-luna","object":"prompt_answer","platform":"chatgpt","prompt_hash":"6f1ed002ab5595859014ebf0951522d9c47f3ab1","prompt_text":"Which running shoes are best for a first marathon?","rank":2,"report_id":"8a72d9f1-c4b5-4e6d-9b1f-0e3a2c6d8b04","report_name":"Weekly US tracking"}},"PromptAnswerBrand":{"properties":{"name":{"type":"string","title":"Name","description":"The brand's own name, a registered competitor's canonical name, or the name as the answer wrote it."},"category":{"type":"string","title":"Category","description":"`my_brand`, `direct_competitor`, `indirect_competitor`, `ai_platform`, `publisher`, `other` or `uncategorized` (an open set): a registered competitor's relation in the brand's registry, else the answers' own."}},"additionalProperties":false,"type":"object","required":["name","category"],"title":"PromptAnswerBrand","description":"A brand an answer names."},"PromptAnswerBrandCount":{"properties":{"object":{"type":"string","const":"prompt_answer_brand_count","title":"Object","description":"Always `prompt_answer_brand_count`.","default":"prompt_answer_brand_count"},"name":{"type":"string","title":"Name","description":"The brand's own name, a registered competitor's canonical name, or the name as the answers wrote it."},"category":{"type":"string","title":"Category","description":"`my_brand`, `direct_competitor`, `indirect_competitor`, `ai_platform`, `publisher`, `other` or `uncategorized` (an open set): a registered competitor's relation in the brand's registry, else the answers' own."},"answers":{"type":"integer","minimum":1.0,"title":"Answers","description":"Answers naming it, each counted once; the brand counts exactly where `brand_appears` is true."},"position":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Position","description":"Its mean first place among the brands each of those answers names, 1 is first; `null` when none of them lists it in order."}},"additionalProperties":false,"type":"object","required":["name","category","answers","position"],"title":"PromptAnswerBrandCount","description":"A brand the answers under the filters name, and in how many of them.","example":{"answers":214,"category":"direct_competitor","name":"Nike","object":"prompt_answer_brand_count","position":1.8}},"PromptAnswerBrandCountList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/PromptAnswerBrandCount"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"True when more items exist past this page. Fetch them with a larger `offset`."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of items matching the query, across all pages."},"limit":{"type":"integer","minimum":1.0,"title":"Limit","description":"Page size that was applied."},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of items skipped before this page."}},"additionalProperties":false,"type":"object","required":["data","has_more","total","limit","offset"],"title":"PromptAnswerBrandCountList","description":"A page of the brands the answers name, most named first.","example":{"data":[{"answers":214,"category":"direct_competitor","name":"Nike","object":"prompt_answer_brand_count","position":1.8}],"has_more":false,"limit":10,"object":"list","offset":0,"total":1}},"PromptAnswerDetail":{"properties":{"object":{"type":"string","const":"prompt_answer_detail","title":"Object","description":"Always `prompt_answer_detail`.","default":"prompt_answer_detail"},"id":{"type":"string","title":"Id","description":"The answer id."},"prompt_text":{"type":"string","title":"Prompt Text","description":"The prompt as sent to the engine."},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category","description":"The prompt's category."},"platform":{"type":"string","title":"Platform","description":"The engine that answered (an open set, e.g. `chatgpt`, `gemini`)."},"model_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model Version","description":"Model that answered, when it was recorded."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the engine answered."},"brand_appears":{"type":"boolean","title":"Brand Appears","description":"True when the answer names the brand."},"rank":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Rank","description":"The brand's position in the answer."},"response":{"type":"string","title":"Response","description":"The answer text as the engine returned it."},"citations":{"items":{"$ref":"#/components/schemas/ReportCitation"},"type":"array","title":"Citations","description":"Pages the answer cites, with what the engine returned for each."},"retrieved":{"items":{"$ref":"#/components/schemas/ReportCitation"},"type":"array","title":"Retrieved","description":"Pages the engine read while answering that its text does not cite; never in `citations`. Empty for Perplexity and Google AI Mode, whose sources are all cited. Claude, Gemini and Grok answers recorded before 2026-10-29 list these pages in `citations` too."},"fanouts":{"items":{"type":"string"},"type":"array","title":"Fanouts","description":"The web searches the engine ran to write this answer (fan-outs), in its order. Filled for ChatGPT, Claude, Gemini, Grok, Perplexity and Muse; empty for Google AI Mode, which does not report them."},"businesses_categorized":{"items":{"$ref":"#/components/schemas/BusinessCategorized"},"type":"array","title":"Businesses Categorized","description":"Businesses the answer names, each with its category and the reason for it."}},"additionalProperties":false,"type":"object","required":["id","prompt_text","platform","created_at","brand_appears","response","citations","retrieved","businesses_categorized"],"title":"PromptAnswerDetail","description":"One engine answer in full: its text, the pages it cites and read, and the businesses it names.","example":{"brand_appears":true,"businesses_categorized":[{"category":"direct_competitor","name":"Nike","object":"business_categorized"}],"category":"Marathon","citations":[{"object":"citation","title":"The Best Running Shoes of 2026","url":"https://www.runnersworld.com/gear/a20865766/best-running-shoes/"}],"created_at":"2026-09-20T08:15:00Z","fanouts":["best running shoes 2026","nike vs asics running shoes"],"id":"3c9e2f4a-1b2d-4e5f-8a6b-7c8d9e0f1a2b","model_version":"gpt-6-luna","object":"prompt_answer_detail","platform":"chatgpt","prompt_text":"Which running shoes are best for a first marathon?","rank":2,"response":"For a first marathon, the adidas Adizero Boston 12 is frequently recommended...","retrieved":[]}},"PromptAnswerList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/PromptAnswer"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Opaque continuation token. Pass back as `?cursor=` to fetch the next page. `null` when `has_more` is false."}},"additionalProperties":false,"type":"object","required":["data","has_more"],"title":"PromptAnswerList","description":"Cursor-paginated answers, newest first.","example":{"data":[{"brand_appears":true,"brands_named":[{"category":"my_brand","name":"adidas"},{"category":"direct_competitor","name":"Nike"}],"category":"Marathon","citation_count":6,"created_at":"2026-09-20T08:15:00Z","id":"3c9e2f4a-1b2d-4e5f-8a6b-7c8d9e0f1a2b","model_version":"gpt-6-luna","object":"prompt_answer","platform":"chatgpt","prompt_hash":"6f1ed002ab5595859014ebf0951522d9c47f3ab1","prompt_text":"Which running shoes are best for a first marathon?","rank":2,"report_id":"8a72d9f1-c4b5-4e6d-9b1f-0e3a2c6d8b04","report_name":"Weekly US tracking"}],"has_more":false,"object":"list"}},"PromptAnswerPoint":{"properties":{"object":{"type":"string","const":"prompt_answer_point","title":"Object","description":"Always `prompt_answer_point`.","default":"prompt_answer_point"},"day":{"type":"string","format":"date","title":"Day","description":"The day the answers were given, in the `tz` asked (default UTC)."},"platform":{"type":"string","title":"Platform","description":"The engine that answered (an open set, e.g. `chatgpt`, `gemini`)."},"answers":{"type":"integer","minimum":0.0,"title":"Answers","description":"Answers the engine gave that day under the filters."},"mentioned":{"type":"integer","minimum":0.0,"title":"Mentioned","description":"Of those, the answers that named the brand."}},"additionalProperties":false,"type":"object","required":["day","platform","answers","mentioned"],"title":"PromptAnswerPoint","description":"The answers one engine gave to the brand's prompts on one day, and how many named the brand.","example":{"answers":48,"day":"2026-09-20","mentioned":19,"object":"prompt_answer_point","platform":"chatgpt"}},"PromptAnswerSeries":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/PromptAnswerPoint"},"type":"array","title":"Data"}},"additionalProperties":false,"type":"object","required":["data"],"title":"PromptAnswerSeries","description":"Answers per day and engine, oldest day first.","example":{"data":[{"answers":48,"day":"2026-09-20","mentioned":19,"object":"prompt_answer_point","platform":"chatgpt"}],"object":"list"}},"PromptAutoGenerate":{"properties":{"prompts_per_category":{"type":"integer","maximum":50.0,"minimum":1.0,"title":"Prompts Per Category","description":"How many prompts to generate **per category**. The actual total is `prompts_per_category * len(categories)` and must not push the report past `50` total prompts."},"categories":{"items":{"type":"string"},"type":"array","maxItems":30,"minItems":1,"title":"Categories","description":"Category buckets to seed prompt generation. At least one required."}},"additionalProperties":false,"type":"object","required":["prompts_per_category","categories"],"title":"PromptAutoGenerate","description":"LLM seed for auto-mode prompt generation (synchronous, ~10-30s)."},"PromptBulkCreate":{"properties":{"prompts":{"anyOf":[{"items":{"$ref":"#/components/schemas/PromptInput"},"type":"array","maxItems":50},{"type":"null"}],"title":"Prompts","description":"Up to 50 caller-supplied prompts. Mutually exclusive with `auto_generate`."},"auto_generate":{"anyOf":[{"$ref":"#/components/schemas/PromptAutoGenerate"},{"type":"null"}],"description":"LLM-driven prompt ideation. Synchronous (10-30s). Mutually exclusive with `prompts`."},"replace":{"type":"boolean","title":"Replace","description":"With `auto_generate`, `true` replaces the report's prompts with the generated set (they are put back if generation fails); default `false` adds to them.","default":false}},"additionalProperties":false,"type":"object","title":"PromptBulkCreate","description":"Body for ``POST /v1/reports/{id}/prompts``. Provide exactly one of `prompts` or `auto_generate`.","examples":[{"prompts":[{"category":"CRM Software","intent":"consideration","prompt_text":"best CRM for SaaS startups"},{"category":"CRM Software","prompt_text":"Salesforce alternatives"}]},{"auto_generate":{"categories":["CRM Software","Marketing Automation","Email Marketing"],"prompts_per_category":5}}]},"PromptBulkCreated":{"properties":{"object":{"type":"string","title":"Object","description":"Always `list`.","default":"list"},"data":{"items":{"$ref":"#/components/schemas/Prompt"},"type":"array","title":"Data","description":"The freshly created prompts."}},"additionalProperties":false,"type":"object","required":["data"],"title":"PromptBulkCreated","description":"Envelope of freshly created prompts."},"PromptCandidate":{"properties":{"keyword":{"type":"string","title":"Keyword"},"prompt_count":{"type":"integer","title":"Prompt Count","description":"Prompts of the brand that stand for this keyword."},"variants":{"items":{"type":"string"},"type":"array","title":"Variants"},"examples":{"items":{"type":"string"},"type":"array","title":"Examples"}},"type":"object","required":["keyword","prompt_count"],"title":"PromptCandidate"},"PromptCitedPage":{"properties":{"object":{"type":"string","const":"prompt_cited_page","title":"Object","default":"prompt_cited_page"},"url":{"type":"string","title":"Url"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"answers":{"type":"integer","title":"Answers","description":"How many answers to the prompt cite the page."}},"additionalProperties":false,"type":"object","required":["url","answers"],"title":"PromptCitedPage","description":"A page the engines cited answering a prompt, never the brand's own: a source to write or optimize from."},"PromptCitedPageList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/PromptCitedPage"},"type":"array","title":"Data"}},"additionalProperties":false,"type":"object","required":["data"],"title":"PromptCitedPageList","description":"The five pages cited most for a prompt, the most cited first."},"PromptContentSuggestion":{"properties":{"object":{"type":"string","const":"prompt_content_suggestion","title":"Object","default":"prompt_content_suggestion"},"mode":{"type":"string","enum":["optimize","create"],"title":"Mode","description":"`optimize` when a page of the brand is cited for the prompt, `create` when none is."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"The brand's page to optimize; null for `create`."},"suggested_format":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Suggested Format","description":"The content format that fits the prompt (an `AllowedContentTypes` id); null for `optimize`."},"reason":{"type":"string","enum":["own_page_cited","no_page_cited"],"title":"Reason","description":"Why this mode."},"cited_in":{"type":"integer","title":"Cited In","description":"How many answers to the prompt cite the page; 0 for `create`."},"prompt_id":{"type":"string","title":"Prompt Id","description":"The prompt's newest id, for `source_prompt_ids`."},"prompt_text":{"type":"string","title":"Prompt Text","description":"The prompt."},"in_progress":{"anyOf":[{"$ref":"#/components/schemas/PromptContentInProgress"},{"type":"null"}],"description":"Work already under way on the page or the prompt's topic; null when none is. Finish or decide it rather than starting the same thing again."}},"additionalProperties":false,"type":"object","required":["mode","reason","cited_in","prompt_id","prompt_text"],"title":"PromptContentSuggestion","description":"What to do about a prompt the brand is not winning: optimize its page AI cites, or create content."},"PromptDifficulty":{"properties":{"score":{"type":"integer","title":"Score","description":"AI difficulty from 0 to 100, the four components below added up."},"crowding":{"type":"number","title":"Crowding","description":"How many different names share these answers, 0 to 30."},"gatekeeping":{"type":"number","title":"Gatekeeping","description":"How concentrated the citations are in a few domains, 0 to 25."},"stability":{"type":"number","title":"Stability","description":"How little the winners change between runs, 0 to 20."},"entrenchment":{"type":"number","title":"Entrenchment","description":"How fixed the leader's hold is, 0 to 25."},"confidence":{"type":"string","enum":["low","medium","high"],"title":"Confidence","description":"How much data the score is built on."},"sample_size":{"type":"integer","title":"Sample Size","description":"Answers the score was computed from."},"top_competitors":{"items":{"type":"string"},"type":"array","title":"Top Competitors","description":"Names that win these answers most."},"top_domains":{"items":{"type":"string"},"type":"array","title":"Top Domains","description":"Domains cited most in these answers."},"brand_appearance_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Brand Appearance Rate"},"applicable":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Applicable","description":"False when the answers name no business at all."},"computed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Computed At"}},"type":"object","required":["score","crowding","gatekeeping","stability","entrenchment","confidence","sample_size"],"title":"PromptDifficulty","description":"How entrenched the AI answers are for a prompt: high means the same few names always win."},"PromptDiscoveryCreate":{"properties":{"source":{"type":"string","enum":["research","page"],"title":"Source","description":"`research` (needs `seed`) or `page` (needs `url`)."},"seed":{"anyOf":[{"type":"string","maxLength":200,"minLength":2},{"type":"null"}],"title":"Seed","description":"`research`: the keyword to start from."},"mode":{"type":"string","enum":["suggestions","suggestions_exact","ideas","related"],"title":"Mode","description":"`research`: which kind of ideas, as in `POST .../seo/keyword-research`.","default":"suggestions"},"url":{"anyOf":[{"type":"string","maxLength":2000,"minLength":3},{"type":"null"}],"title":"Url","description":"`page`: the page to read."},"country":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Country","description":"`page`: the market as its full English name, e.g. `United States`; the brand's when omitted."},"intent":{"type":"string","enum":["organic","commercial"],"title":"Intent","description":"`page`: `organic` (learning, comparing) or `commercial` (about to choose).","default":"commercial"}},"additionalProperties":false,"type":"object","required":["source"],"title":"PromptDiscoveryCreate","description":"A paid discovery: a keyword research or the prompts one page answers.","example":{"intent":"commercial","source":"page","url":"https://www.asics.com/us/en-us/running-shoes/"}},"PromptInput":{"properties":{"prompt_text":{"type":"string","maxLength":1000,"minLength":1,"title":"Prompt Text","description":"The prompt text to evaluate against the AI platforms."},"category":{"type":"string","maxLength":100,"minLength":1,"title":"Category","description":"Free-form taxonomy bucket. Use a stable string per bucket; this is what powers per-category breakdowns in reports."},"intent":{"anyOf":[{"type":"string","enum":["awareness","consideration","decision"]},{"type":"null"}],"title":"Intent","description":"Optional funnel intent: `awareness`, `consideration` or `decision`. Left out, the prompt stays unclassified."}},"additionalProperties":false,"type":"object","required":["prompt_text","category"],"title":"PromptInput","description":"One prompt in a bulk-create request."},"PromptInsight":{"properties":{"prompt_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prompt Id"},"prompt_text":{"type":"string","title":"Prompt Text"},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category"},"keyword":{"anyOf":[{"$ref":"#/components/schemas/PromptKeywordMapping"},{"type":"null"}],"description":"Null until the prompt is mapped."},"metrics":{"anyOf":[{"$ref":"#/components/schemas/KeywordMetrics"},{"type":"null"}]},"difficulty":{"anyOf":[{"$ref":"#/components/schemas/PromptDifficulty"},{"type":"null"}]},"tracked":{"type":"boolean","title":"Tracked","description":"The head keyword is tracked for Google positions."}},"type":"object","required":["prompt_text","tracked"],"title":"PromptInsight"},"PromptInsights":{"properties":{"object":{"type":"string","const":"prompt_insights","title":"Object","default":"prompt_insights"},"report_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Report Id"},"data":{"items":{"$ref":"#/components/schemas/PromptInsight"},"type":"array","title":"Data"},"target":{"$ref":"#/components/schemas/KeywordTarget"},"pending":{"type":"integer","title":"Pending","description":"Prompts not mapped yet; a completed report maps them within minutes."},"metrics_pending":{"type":"integer","title":"Metrics Pending","description":"Head keywords whose Google numbers are still being bought."}},"type":"object","required":["data","target","pending","metrics_pending"],"title":"PromptInsights","description":"The Google keyword behind each AI prompt, its search demand, and how hard the AI answer is to win."},"PromptInsightsLookup":{"properties":{"prompt_texts":{"items":{"type":"string"},"type":"array","maxItems":500,"minItems":1,"title":"Prompt Texts","description":"Prompt texts of the brand."}},"additionalProperties":false,"type":"object","required":["prompt_texts"],"title":"PromptInsightsLookup"},"PromptKeywordMapping":{"properties":{"head_keyword":{"type":"string","title":"Head Keyword","description":"The Google keyword the prompt stands for."},"modifiers":{"items":{"type":"string"},"type":"array","title":"Modifiers"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language"},"intent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Intent"},"entity_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Type"},"is_local":{"type":"boolean","title":"Is Local","default":false},"locality":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Locality"},"source":{"type":"string","enum":["llm","manual"],"title":"Source"}},"type":"object","required":["head_keyword","source"],"title":"PromptKeywordMapping"},"PromptKeywordPin":{"properties":{"prompt_text":{"type":"string","maxLength":2000,"minLength":1,"title":"Prompt Text"},"head_keyword":{"type":"string","maxLength":200,"minLength":1,"title":"Head Keyword","description":"The keyword the prompt stands for."}},"additionalProperties":false,"type":"object","required":["prompt_text","head_keyword"],"title":"PromptKeywordPin"},"PromptList":{"properties":{"object":{"type":"string","title":"Object","description":"Always `list`.","default":"list"},"data":{"items":{"$ref":"#/components/schemas/Prompt"},"type":"array","title":"Data","description":"Prompts attached to the report (capped at 50)."}},"additionalProperties":false,"type":"object","required":["data"],"title":"PromptList","description":"Envelope of a report's prompts (`GET /v1/reports/{id}/prompts`).","example":{"data":[{"brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","category":"Running Shoes","created_at":"2026-04-01T11:00:00+00:00","id":"018e7c2c-33ab-7df1-b1cd-2ac3a8f9112d","intent":"consideration","object":"prompt","prompt_text":"What are the best running shoes for a first marathon?","report_id":"8a72d9f1-c4b5-4e6d-9b1f-0e3a2c6d8b04"}],"object":"list"}},"PromptUpdate":{"properties":{"prompt_text":{"anyOf":[{"type":"string","maxLength":1000,"minLength":1},{"type":"null"}],"title":"Prompt Text"},"category":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Category"},"intent":{"anyOf":[{"type":"string","enum":["awareness","consideration","decision"]},{"type":"null"}],"title":"Intent","description":"New funnel intent: `awareness`, `consideration` or `decision`; `null` makes it unclassified."}},"additionalProperties":false,"type":"object","title":"PromptUpdate","description":"Partial-update body for `PATCH /v1/reports/{report_id}/prompts/{id}`."},"Prospect":{"properties":{"object":{"type":"string","const":"prospect","title":"Object","default":"prospect"},"id":{"type":"string","title":"Id"},"list_id":{"type":"string","title":"List Id"},"company_name":{"type":"string","title":"Company Name"},"website":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Website"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"contact_email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contact Email"},"contact_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contact Name"},"contact_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contact Title"},"linkedin_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Linkedin Url"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone"},"address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address"},"rating":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Rating"},"reviews_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Reviews Count"},"status":{"type":"string","enum":["new","generating","ready","contacted","following_up","replied","won","lost"],"title":"Status","description":"`new`, `generating`, `ready`, `contacted`, `following_up`, `replied`, `won` or `lost`."},"brand_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brand Id","description":"The brand its report runs on, once one was made."},"report_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Report Id"},"has_pitch":{"type":"boolean","title":"Has Pitch","description":"Whether a pitch email was written for it."},"opportunity_score":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Opportunity Score","description":"Who to call first, 0 to 100: Google demand, reviews, how reachable a contact is and what its website leaves to fix for AI engines (structured data, llms.txt, speed), times the gap in AI answers. Null until scored."},"demand_skip":{"anyOf":[{"type":"string","enum":["platform","repeated_domain","branch_page"]},{"type":"null"}],"title":"Demand Skip","description":"Why its website's Google demand is left out of the score: `platform` (a booking or site builder page), `repeated_domain` (the domain of businesses at other places too, a chain) or `branch_page` (a location page of a larger site). Null when it counts."},"organic_keywords":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Organic Keywords","description":"Google keywords its site ranks for, when read."},"organic_traffic":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Organic Traffic","description":"Estimated monthly Google visits, when read."},"ai_visibility_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ai Visibility Score","description":"Visibility score of its report, once run."},"scored_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scored At"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source","description":"`maps`, `ai`, `merged`, `widget`, `hosted`, `competitor` or `citation`. The set is open."},"lost_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lost Reason","description":"Why a lost deal was lost: `price`, `no_budget`, `chose_competitor`, `no_response`, `not_a_fit`, `timing` or `other`."},"revisit_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Revisit At","description":"Day a lost deal is due another look."},"won_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Won At"},"lost_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lost At"},"report_viewed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Report Viewed At","description":"When the prospect first opened the report."},"report_error_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Report Error Code","description":"Why its last report could not be built or run: `insufficient_credits`, `brand_limit`, `research_failed`, `timed_out`, `out_of_credits`, `stuck`, `engines_failed` or `failed`. Null once another starts. The set is open."},"contact_lookup_started_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contact Lookup Started At","description":"When the running contact lookup started; null when none runs."},"score_queued_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Score Queued At","description":"When an imported prospect was queued for its score; it is scored once `scored_at` passes it."},"pipeline_stage":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pipeline Stage","description":"Where it stands in the outreach pipeline: `found`, `report` (its report runs, or is done with no pitch yet), `drafted` (a pitch waits for approval), `approved`, `sent` or `closed` (won or lost). The set is open."},"report_stage":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Report Stage","description":"Where a report build stands before its run: `researching`, `prompts` or `starting`. Null otherwise."},"pitch_approved_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pitch Approved At","description":"When its pitch was approved for sending."},"pitch_queued_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pitch Queued At","description":"When a pitch was queued to be written for it."},"send_queued_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Send Queued At","description":"When its outreach was queued to start."},"not_ready_reasons":{"items":{"type":"string"},"type":"array","title":"Not Ready Reasons","description":"Why its outreach cannot go out as it stands (`no_contact_email`, `report_running`, `nothing_to_send`, `empty_subject`, `empty_body`); empty when it can. A prospect with any is never sent. The set is open."},"profile_audit":{"anyOf":[{"$ref":"#/components/schemas/ProspectProfileAuditSummary"},{"type":"null"}],"description":"Its newest Business Profile audit; null before the first (`POST .../profile-audits` runs one)."},"profile_auditable":{"type":"boolean","title":"Profile Auditable","description":"Whether its Business Profile can be audited: it has a Google place, or a name with a city or an address.","default":false},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated At"}},"additionalProperties":false,"type":"object","required":["id","list_id","company_name","status","has_pitch"],"title":"Prospect","description":"A saved prospect."},"ProspectBusiness":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"place_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Place Id"},"city":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"City"},"website":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Website"},"maps_uri":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Maps Uri"},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category"},"rating":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Rating"},"reviews":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Reviews"},"photos":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Photos"},"review_topics":{"items":{"type":"string"},"type":"array","title":"Review Topics","description":"What its Google reviews talk about most."},"third_party":{"additionalProperties":{"anyOf":[{"additionalProperties":{"anyOf":[{"type":"number"},{"type":"integer"},{"type":"null"}]},"type":"object"},{"type":"null"}]},"type":"object","title":"Third Party","description":"Its `trustpilot` and `tripadvisor` reviews when it has them: `rating`, `reviews`, how many were `read` and how many of those were `answered`. Null where none was found."},"matched_by":{"anyOf":[{"type":"string","enum":["place","website","name_city","name"]},{"type":"null"}],"title":"Matched By","description":"How the business read is the prospect: its Google `place` id, its `website`'s domain, its name by whole words in its city (`name_city`), or its `name` alone where neither side names a city. Null on audits run before it was kept."}},"additionalProperties":false,"type":"object","title":"ProspectBusiness","description":"The business a profile audit read, from what Google shows anyone."},"ProspectCandidate":{"properties":{"company_name":{"type":"string","title":"Company Name"},"website":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Website"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"contact_email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contact Email"},"contact_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contact Name"},"contact_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contact Title"},"linkedin_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Linkedin Url"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone"},"address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address"},"rating":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Rating"},"reviews_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Reviews Count"},"source":{"type":"string","title":"Source","description":"`maps`, `ai` or `merged`."},"duplicate":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Duplicate","description":"Where the business already sits for the account: `new`, `in_this_list`, `in_other_list`, `client` or `lost`. The set is open."},"duplicate_list_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Duplicate List Name","description":"The list holding it, when it sits in one."},"ai_named":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Ai Named","description":"Whether the AI platforms named it; null when not asked."},"ai_engines_named":{"items":{"type":"string"},"type":"array","title":"Ai Engines Named","description":"The AI platforms that named it."}},"additionalProperties":false,"type":"object","required":["company_name","source"],"title":"ProspectCandidate","description":"A company the search found; save the ones worth keeping in the app."},"ProspectContactLookup":{"properties":{"object":{"type":"string","const":"prospect.contact_lookup","title":"Object","default":"prospect.contact_lookup"},"prospect_id":{"type":"string","title":"Prospect Id"},"found":{"type":"boolean","title":"Found","description":"Whether someone was found; their email, name and title are on the prospect."},"credits_charged":{"type":"integer","title":"Credits Charged","description":"1 when a contact was found, 0 when not (refunded)."},"prospect":{"$ref":"#/components/schemas/Prospect"}},"additionalProperties":false,"type":"object","required":["prospect_id","found","credits_charged","prospect"],"title":"ProspectContactLookup","description":"A contact looked up on the prospect's own website domain."},"ProspectFunnel":{"properties":{"object":{"type":"string","const":"prospect_funnel","title":"Object","default":"prospect_funnel"},"counts":{"$ref":"#/components/schemas/ProspectFunnelCounts"},"total":{"type":"integer","title":"Total","default":0},"outbound":{"$ref":"#/components/schemas/ProspectOriginFunnel"},"widget":{"$ref":"#/components/schemas/ProspectOriginFunnel"},"reports":{"$ref":"#/components/schemas/ProspectOriginFunnel","description":"Prospects added from what the clients' reports named."},"lost_by_reason":{"additionalProperties":{"type":"integer"},"type":"object","title":"Lost By Reason","description":"Lost deals by reason: `price`, `no_budget`, `chose_competitor`, `no_response`, `not_a_fit`, `timing`, `other`, or `unknown` for deals lost before a reason was asked. The set is open."}},"additionalProperties":false,"type":"object","required":["counts","outbound","widget","reports"],"title":"ProspectFunnel","description":"The pipeline across every list, split into the prospects searched for, the widget's leads and the businesses\nadded from the clients' reports, with the lost deals by reason."},"ProspectFunnelCounts":{"properties":{"new":{"type":"integer","title":"New","default":0},"generating":{"type":"integer","title":"Generating","default":0},"ready":{"type":"integer","title":"Ready","default":0},"contacted":{"type":"integer","title":"Contacted","default":0},"following_up":{"type":"integer","title":"Following Up","default":0},"replied":{"type":"integer","title":"Replied","default":0},"won":{"type":"integer","title":"Won","default":0},"lost":{"type":"integer","title":"Lost","default":0}},"additionalProperties":false,"type":"object","title":"ProspectFunnelCounts","description":"Prospects per stage."},"ProspectList":{"properties":{"object":{"type":"string","const":"prospect_list","title":"Object","default":"prospect_list"},"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"sector":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sector"},"location":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location"},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language"},"prospect_count":{"type":"integer","title":"Prospect Count","default":0},"website_leads":{"type":"boolean","title":"Website Leads","description":"The list that holds the site widget's leads; nothing is saved into it."},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"}},"additionalProperties":false,"type":"object","required":["id","name","website_leads"],"title":"ProspectList","description":"A prospect list."},"ProspectListDetail":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/Prospect"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"True when more items exist past this page. Fetch them with a larger `offset`."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of items matching the query, across all pages."},"limit":{"type":"integer","minimum":1.0,"title":"Limit","description":"Page size that was applied."},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of items skipped before this page."},"prospect_list":{"$ref":"#/components/schemas/ProspectList","description":"The list itself."}},"additionalProperties":false,"type":"object","required":["data","has_more","total","limit","offset","prospect_list"],"title":"ProspectListDetail","description":"A prospect list and a page of its prospects, newest first."},"ProspectListList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/ProspectList"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"True when more items exist past this page. Fetch them with a larger `offset`."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of items matching the query, across all pages."},"limit":{"type":"integer","minimum":1.0,"title":"Limit","description":"Page size that was applied."},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of items skipped before this page."}},"additionalProperties":false,"type":"object","required":["data","has_more","total","limit","offset"],"title":"ProspectListList","description":"A page of the account's prospect lists, newest first."},"ProspectOriginFunnel":{"properties":{"counts":{"$ref":"#/components/schemas/ProspectFunnelCounts"},"total":{"type":"integer","title":"Total","default":0}},"additionalProperties":false,"type":"object","required":["counts"],"title":"ProspectOriginFunnel","description":"One origin's pipeline."},"ProspectPipeline":{"properties":{"object":{"type":"string","const":"prospect_pipeline","title":"Object","default":"prospect_pipeline"},"list_id":{"type":"string","title":"List Id"},"counts":{"$ref":"#/components/schemas/ProspectPipelineCounts"},"stages":{"additionalProperties":{"items":{"$ref":"#/components/schemas/Prospect"},"type":"array"},"type":"object","title":"Stages","description":"Per stage (`found`, `report`, `drafted`, `approved`, `sent`), its best prospects by opportunity score, up to `per_stage`. The set of stages is open."}},"additionalProperties":false,"type":"object","required":["list_id","counts"],"title":"ProspectPipeline","description":"A prospect list as its outreach pipeline."},"ProspectPipelineCounts":{"properties":{"found":{"type":"integer","title":"Found","default":0},"report":{"type":"integer","title":"Report","default":0},"drafted":{"type":"integer","title":"Drafted","default":0},"approved":{"type":"integer","title":"Approved","default":0},"sent":{"type":"integer","title":"Sent","default":0},"closed":{"type":"integer","title":"Closed","default":0},"pitch_queued":{"type":"integer","title":"Pitch Queued","description":"Pitches queued to be written.","default":0},"send_queued":{"type":"integer","title":"Send Queued","description":"Outreach queued to start.","default":0},"without_email":{"type":"integer","title":"Without Email","description":"Prospects with no contact email, never sent.","default":0}},"additionalProperties":false,"type":"object","title":"ProspectPipelineCounts","description":"A list's prospects per outreach stage, with what is queued and how many have no address to send to."},"ProspectPipelineRun":{"properties":{"object":{"type":"string","const":"prospect_pipeline.run","title":"Object","default":"prospect_pipeline.run"},"list_id":{"type":"string","title":"List Id"},"action":{"type":"string","enum":["report","pitch","approve","send","audit"],"title":"Action"},"started":{"type":"integer","title":"Started","description":"Prospects whose step was queued."},"prospect_ids":{"items":{"type":"string"},"type":"array","title":"Prospect Ids","description":"The prospects started."},"job_ids":{"additionalProperties":{"type":"string"},"type":"object","title":"Job Ids","description":"An `audit` run's job of each prospect started, by prospect id: poll `GET /v1/jobs/{job_id}`, then read the audit by the same id. Empty for the other actions."},"skipped":{"additionalProperties":{"type":"integer"},"type":"object","title":"Skipped","description":"Left out, by reason: `not_found`, `running`, `no_website`, `has_report`, `brand_limit`, `has_pitch`, `report_failed`, `sent`, `not_drafted`, `not_approved`, `not_ready`, `already_contacted`, `not_auditable`, `credits` or `not_queued`. The set is open."},"credits_reserved_estimate":{"type":"integer","title":"Credits Reserved Estimate","description":"What the started reports, pitches and audits are expected to charge as they run.","default":0}},"additionalProperties":false,"type":"object","required":["list_id","action","started"],"title":"ProspectPipelineRun","description":"202 envelope: what a pipeline run started in the background, and what it left out and why."},"ProspectPipelineRunRequest":{"properties":{"action":{"type":"string","enum":["report","pitch","approve","send","audit"],"title":"Action","description":"`report` builds the report of each prospect with a website and none yet; `pitch` writes the pitch of each one with a finished report, or a quick pitch from what the search found when it has none; `approve` approves each drafted pitch that is ready to send; `send` starts the outreach of each approved one; `audit` audits the Business Profile of each one that can be audited (`profile_auditable`), 2 credits each."},"prospect_ids":{"items":{"type":"string"},"type":"array","maxItems":100,"minItems":1,"title":"Prospect Ids","description":"Prospects of this list, up to 100."},"then_pitch":{"type":"boolean","title":"Then Pitch","description":"With `report`: write the pitch once the report is ready.","default":true}},"additionalProperties":false,"type":"object","required":["action","prospect_ids"],"title":"ProspectPipelineRunRequest","description":"Move chosen prospects of a list one stage on.","example":{"action":"pitch","prospect_ids":["b0000000-0000-0000-0000-000000000001"]}},"ProspectPitch":{"properties":{"object":{"type":"string","const":"prospect.pitch","title":"Object","default":"prospect.pitch"},"prospect_id":{"type":"string","title":"Prospect Id"},"subject":{"type":"string","title":"Subject"},"body":{"type":"string","title":"Body"}},"additionalProperties":false,"type":"object","required":["prospect_id","subject","body"],"title":"ProspectPitch","description":"A pitch email written from the prospect's report, saved on the prospect."},"ProspectProfileAudit":{"properties":{"object":{"type":"string","const":"prospect_profile_audit","title":"Object","default":"prospect_profile_audit"},"id":{"type":"string","title":"Id"},"prospect_id":{"type":"string","title":"Prospect Id"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Created At"},"score":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Score"},"measured":{"type":"integer","title":"Measured"},"total":{"type":"integer","title":"Total"},"counts":{"additionalProperties":{"type":"integer"},"type":"object","title":"Counts","description":"Checks per status: pass, warn, fail, not_measurable."},"checks":{"items":{"$ref":"#/components/schemas/GbpAuditCheck"},"type":"array","title":"Checks","description":"Every check; what only the owner sees reads `not_measurable` with reason `needs_access`."},"business":{"$ref":"#/components/schemas/ProspectBusiness"}},"additionalProperties":false,"type":"object","required":["id","prospect_id","score","measured","total","counts","business"],"title":"ProspectProfileAudit","description":"A prospect's Business Profile audit in full: the score over what the public data measured, the coverage,\nevery check and the business read."},"ProspectProfileAuditDispatched":{"properties":{"object":{"type":"string","const":"prospect_profile_audit_job","title":"Object","default":"prospect_profile_audit_job"},"job_id":{"type":"string","title":"Job Id","description":"Poll `GET /v1/jobs/{job_id}` until `status` is `completed` or `failed`."},"audit_id":{"type":"string","title":"Audit Id","description":"Read the audit with `GET /v1/agency/prospects/{prospect_id}/profile-audits/{audit_id}`."}},"additionalProperties":false,"type":"object","required":["job_id","audit_id"],"title":"ProspectProfileAuditDispatched","description":"A queued profile audit: poll its job, then read the audit by the same id."},"ProspectProfileAuditList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/ProspectProfileAuditListItem"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Opaque continuation token. Pass back as `?cursor=` to fetch the next page. `null` when `has_more` is false."}},"additionalProperties":false,"type":"object","required":["data","has_more"],"title":"ProspectProfileAuditList","description":"A page of a prospect's Business Profile audits, newest first."},"ProspectProfileAuditListItem":{"properties":{"id":{"type":"string","title":"Id"},"score":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Score","description":"0 to 100 over the checks the public data could measure."},"measured":{"type":"integer","title":"Measured","description":"Checks measured, of `total`."},"total":{"type":"integer","title":"Total"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Created At"},"object":{"type":"string","const":"prospect_profile_audit","title":"Object","default":"prospect_profile_audit"},"business":{"$ref":"#/components/schemas/ProspectBusiness"}},"additionalProperties":false,"type":"object","required":["id","score","measured","total","business"],"title":"ProspectProfileAuditListItem","description":"One profile audit in the prospect's list."},"ProspectProfileAuditSummary":{"properties":{"id":{"type":"string","title":"Id"},"score":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Score","description":"0 to 100 over the checks the public data could measure."},"measured":{"type":"integer","title":"Measured","description":"Checks measured, of `total`."},"total":{"type":"integer","title":"Total"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Created At"}},"additionalProperties":false,"type":"object","required":["id","score","measured","total"],"title":"ProspectProfileAuditSummary","description":"A prospect's Business Profile audit in a line."},"ProspectReportDispatched":{"properties":{"object":{"type":"string","const":"prospect.report","title":"Object","default":"prospect.report"},"prospect_id":{"type":"string","title":"Prospect Id"},"brand_id":{"type":"string","title":"Brand Id"},"report_id":{"type":"string","title":"Report Id","description":"Read it with `GET /v1/reports/{report_id}`; until its first run starts it is the draft's id, which the run's report keeps."},"tracker_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tracker Id","description":"The tracker (the report's definition) it is a result of."},"job_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Id","description":"Poll `GET /v1/jobs/{job_id}`; null when it was already running."}},"additionalProperties":false,"type":"object","required":["prospect_id","brand_id","report_id"],"title":"ProspectReportDispatched","description":"202 envelope: the report is built and its run is queued."},"ProspectReportRequest":{"properties":{"ai_platforms":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":10,"minItems":1},{"type":"null"}],"title":"Ai Platforms","description":"Engines, e.g. `chatgpt`, `claude`, `ai_overviews`."},"num_prompts":{"anyOf":[{"type":"integer","maximum":50.0,"minimum":1.0},{"type":"null"}],"title":"Num Prompts","description":"Prompts to generate and ask."},"country":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Country","description":"Full English name, e.g. `United States`."},"location":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Location","description":"City or region inside the country."},"language":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Language","description":"e.g. `English`."}},"additionalProperties":false,"type":"object","title":"ProspectReportRequest","description":"How the prospect's report runs; anything left out comes from the list's report setup, then the account's.","example":{"ai_platforms":["chatgpt","claude","ai_overviews"],"num_prompts":5}},"ProspectReportView":{"properties":{"object":{"type":"string","const":"prospect_report_view","title":"Object","default":"prospect_report_view"},"id":{"type":"string","title":"Id","description":"The prospect's id."},"list_id":{"type":"string","title":"List Id"},"company_name":{"type":"string","title":"Company Name"},"website":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Website"},"contact_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contact Name"},"contact_email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contact Email"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone"},"status":{"type":"string","title":"Status"},"source":{"type":"string","title":"Source"},"report_viewed_at":{"type":"string","title":"Report Viewed At","description":"When they first opened the report."},"report_view_count":{"type":"integer","title":"Report View Count","description":"How many times it was opened, never by the account.","default":0}},"additionalProperties":false,"type":"object","required":["id","list_id","company_name","status","source","report_viewed_at"],"title":"ProspectReportView","description":"A prospect or a widget lead who opened the report they were sent."},"ProspectReportViewList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/ProspectReportView"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Opaque continuation token. Pass back as `?cursor=` to fetch the next page. `null` when `has_more` is false."}},"additionalProperties":false,"type":"object","required":["data","has_more"],"title":"ProspectReportViewList","description":"A page of who opened their report and waits on the agency, newest open first."},"ProspectSaveItem":{"properties":{"company_name":{"type":"string","maxLength":200,"minLength":1,"title":"Company Name"},"website":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Website"},"description":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Description"},"contact_email":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Contact Email"},"contact_name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Contact Name"},"contact_title":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Contact Title"},"linkedin_url":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Linkedin Url"},"phone":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"title":"Phone"},"address":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Address"},"rating":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Rating"},"reviews_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Reviews Count"},"place_id":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Place Id","description":"Google place id, when it came from Maps."},"source":{"type":"string","enum":["ai","maps","merged","competitor","citation"],"title":"Source","description":"Where it came from: a search (`maps`, `ai`, `merged`) or the clients' reports.","default":"ai"},"source_brand_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Brand Id","description":"The client brand whose reports named it."},"ai_named":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Ai Named","description":"Whether the AI platforms named it, from a search probe."}},"additionalProperties":false,"type":"object","required":["company_name"],"title":"ProspectSaveItem","description":"A business to save into a list: a search candidate, a suggestion, or one you found yourself."},"ProspectSaveRequest":{"properties":{"prospects":{"items":{"$ref":"#/components/schemas/ProspectSaveItem"},"type":"array","maxItems":50,"minItems":1,"title":"Prospects"},"include_duplicates":{"type":"boolean","title":"Include Duplicates","description":"Also save businesses that are a client of the account; one already in this list is never saved twice.","default":false}},"additionalProperties":false,"type":"object","required":["prospects"],"title":"ProspectSaveRequest","description":"Businesses to save into a list.","example":{"prospects":[{"company_name":"Blue Bottle Coffee","source":"maps","website":"https://bluebottlecoffee.com"}]}},"ProspectSaveResult":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/Prospect"},"type":"array","title":"Data"},"saved":{"type":"integer","title":"Saved","default":0},"skipped_by_class":{"additionalProperties":{"type":"integer"},"type":"object","title":"Skipped By Class","description":"Left out by where they already sat: `in_this_list`, `client`. The set is open."}},"additionalProperties":false,"type":"object","required":["data"],"title":"ProspectSaveResult","description":"The prospects saved, and how many were left out and why."},"ProspectSearch":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/ProspectCandidate"},"type":"array","title":"Data"},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id"},"credits_charged":{"type":"integer","title":"Credits Charged","default":0},"saved":{"type":"integer","title":"Saved","description":"Businesses saved into `list_id`, when the request named one.","default":0}},"additionalProperties":false,"type":"object","required":["data"],"title":"ProspectSearch","description":"What the search found, kept as the account's latest search."},"ProspectSearchRequest":{"properties":{"sector":{"type":"string","maxLength":200,"minLength":1,"title":"Sector"},"location":{"type":"string","maxLength":200,"minLength":1,"title":"Location"},"country":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Country","description":"Full English name, e.g. `United States`."},"language":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Language"},"probe":{"type":"boolean","title":"Probe","description":"Also ask the AI platforms who they name for the sector and place; no extra credits.","default":false},"list_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"List Id","description":"Save the businesses new to the account into this prospect list, with their Google data."}},"additionalProperties":false,"type":"object","required":["sector","location"],"title":"ProspectSearchRequest","description":"Companies to find by sector and place.","example":{"country":"United States","location":"Austin, Texas","sector":"dental clinics"}},"ProspectSuggestion":{"properties":{"object":{"type":"string","const":"prospect_suggestion","title":"Object","default":"prospect_suggestion"},"domain":{"type":"string","title":"Domain"},"name":{"type":"string","title":"Name"},"website":{"type":"string","title":"Website"},"source":{"type":"string","enum":["competitor","citation"],"title":"Source"},"mentions":{"type":"integer","title":"Mentions","description":"Mentions as a competitor, or pages cited, across the clients' reports."},"brand_ids":{"items":{"type":"string"},"type":"array","title":"Brand Ids","description":"The client brands whose reports name it."},"competes_with":{"items":{"type":"string"},"type":"array","title":"Competes With","description":"Client brand names whose reports name it as a direct competitor."},"duplicate":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Duplicate","description":"Where it already sits: `new`, `in_other_list`, `client` or `lost`. The set is open."}},"additionalProperties":false,"type":"object","required":["domain","name","website","source","mentions","brand_ids","competes_with"],"title":"ProspectSuggestion","description":"A business the engines name for, or cite in, the reports of the account's clients."},"ProspectSuggestionList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/ProspectSuggestion"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"True when more items exist past this page. Fetch them with a larger `offset`."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of items matching the query, across all pages."},"limit":{"type":"integer","minimum":1.0,"title":"Limit","description":"Page size that was applied."},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of items skipped before this page."}},"additionalProperties":false,"type":"object","required":["data","has_more","total","limit","offset"],"title":"ProspectSuggestionList","description":"A page of suggestions: cited businesses, then competitors of no client, then a client's rivals."},"ProspectUpdateRequest":{"properties":{"stage":{"anyOf":[{"type":"string","enum":["won","lost","new"]},{"type":"null"}],"title":"Stage"},"lost_reason":{"anyOf":[{"type":"string","enum":["price","no_budget","chose_competitor","no_response","not_a_fit","timing","other"]},{"type":"null"}],"title":"Lost Reason"},"lost_note":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Lost Note"},"revisit_at":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Revisit At","description":"Day a lost deal is due another look."},"invite_email":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Invite Email","description":"Won: invite this person to a client seat."},"create_tasks":{"type":"boolean","title":"Create Tasks","description":"Won: three kickoff tasks on the client's brand.","default":false},"schedule_report":{"type":"boolean","title":"Schedule Report","description":"Won: a weekly report with the prospect report's prompts and engines.","default":false},"company_name":{"anyOf":[{"type":"string","maxLength":200,"minLength":1},{"type":"null"}],"title":"Company Name"},"website":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Website"},"description":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Description"},"contact_email":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Contact Email"},"contact_name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Contact Name"},"contact_title":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Contact Title"},"phone":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"title":"Phone"},"linkedin_url":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Linkedin Url"}},"additionalProperties":false,"type":"object","title":"ProspectUpdateRequest","description":"A prospect's details, or a move: `won` (with the client's kickoff), `lost` (why, and when to look again), or\n`new` to reopen a lost deal.","example":{"lost_reason":"timing","revisit_at":"2027-04-16","stage":"lost"}},"ProspectUpdated":{"properties":{"object":{"type":"string","const":"prospect.update","title":"Object","default":"prospect.update"},"prospect_id":{"type":"string","title":"Prospect Id"},"status":{"type":"string","enum":["new","generating","ready","contacted","following_up","replied","won","lost"],"title":"Status"},"seat_invited":{"type":"boolean","title":"Seat Invited","default":false},"seat_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Seat Error","description":"Why the client seat could not be invited."},"tasks_created":{"type":"integer","title":"Tasks Created","default":0},"scheduled_report_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scheduled Report Id"}},"additionalProperties":false,"type":"object","required":["prospect_id","status"],"title":"ProspectUpdated","description":"The prospect's stage after the update, and on won what each kickoff step did."},"ProspectingCount":{"properties":{"count":{"type":"integer","title":"Count","default":0},"lists":{"type":"integer","title":"Lists","description":"How many lists hold them.","default":0},"top_list_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Top List Id","description":"The list holding the most of them: where to act first."}},"additionalProperties":false,"type":"object","title":"ProspectingCount","description":"How many prospects sit in one state across every list, and the list holding the most of them."},"ProspectingLeads":{"properties":{"opened":{"$ref":"#/components/schemas/ProspectingCount","description":"Leads who opened their report, not contacted, won or lost yet."},"new_week":{"$ref":"#/components/schemas/ProspectingCount","description":"Leads that came in over the last 7 days."},"report_ready":{"$ref":"#/components/schemas/ProspectingCount","description":"Leads whose report finished, not contacted yet."},"unworked":{"$ref":"#/components/schemas/ProspectingCount","description":"Leads not contacted, won or lost yet."}},"additionalProperties":false,"type":"object","required":["opened","new_week","report_ready","unworked"],"title":"ProspectingLeads","description":"The website's widget leads, counted apart from the prospects."},"ProspectingOutreach":{"properties":{"since":{"type":"string","title":"Since","description":"The first day counted (UTC)."},"days":{"type":"integer","title":"Days","description":"How many days back `since` is, today included."},"sent":{"type":"integer","title":"Sent","default":0},"opened":{"type":"integer","title":"Opened","default":0},"replied":{"type":"integer","title":"Replied","default":0},"by_day":{"items":{"$ref":"#/components/schemas/ProspectingOutreachDay"},"type":"array","title":"By Day","description":"Only the days with sends."}},"additionalProperties":false,"type":"object","required":["since","days"],"title":"ProspectingOutreach","description":"The emails the prospects' campaigns sent since `since` (never the widget leads'), opened and replied to."},"ProspectingOutreachDay":{"properties":{"day":{"type":"string","title":"Day"},"sent":{"type":"integer","title":"Sent","default":0},"opened":{"type":"integer","title":"Opened","default":0},"replied":{"type":"integer","title":"Replied","default":0}},"additionalProperties":false,"type":"object","required":["day"],"title":"ProspectingOutreachDay","description":"One day of the prospects' campaign emails, by the UTC day each was sent."},"ProspectingOverview":{"properties":{"object":{"type":"string","const":"prospecting_overview","title":"Object","default":"prospecting_overview"},"waiting":{"$ref":"#/components/schemas/ProspectingWaiting"},"leads":{"$ref":"#/components/schemas/ProspectingLeads"},"lost_by_reason":{"additionalProperties":{"type":"integer"},"type":"object","title":"Lost By Reason","description":"The prospects' lost deals by reason (never the widget leads'): `price`, `no_budget`, `chose_competitor`, `no_response`, `not_a_fit`, `timing`, `other`, or `unknown`. The set is open."},"outreach":{"$ref":"#/components/schemas/ProspectingOutreach"}},"additionalProperties":false,"type":"object","required":["waiting","leads","outreach"],"title":"ProspectingOverview","description":"What waits on the agency across every list, the prospects' lost deals and the outreach of the last 30 days."},"ProspectingWaiting":{"properties":{"prospect_opened":{"$ref":"#/components/schemas/ProspectingCount","description":"Prospects sent outreach who opened their report and have not replied: the moment to call."},"drafted":{"$ref":"#/components/schemas/ProspectingCount","description":"Pitches written and waiting for review."},"approved":{"$ref":"#/components/schemas/ProspectingCount","description":"Pitches approved and not sent yet."},"not_ready_no_email":{"$ref":"#/components/schemas/ProspectingCount","description":"Pitched prospects with no contact email to send to."},"report_failed":{"$ref":"#/components/schemas/ProspectingCount","description":"Reports that did not come out."},"pitch_failed":{"$ref":"#/components/schemas/ProspectingCount","description":"Queued pitches that were not written."},"send_failed":{"$ref":"#/components/schemas/ProspectingCount","description":"Queued outreach that did not start."}},"additionalProperties":false,"type":"object","required":["prospect_opened","drafted","approved","not_ready_no_email","report_failed","pitch_failed","send_failed"],"title":"ProspectingWaiting","description":"What waits on the agency across every list, only the prospects it goes after (outbound and from the clients'\nreports), never the website's widget leads."},"PublishScheduleMove":{"properties":{"run_at":{"type":"string","format":"date-time","title":"Run At","description":"When the queued publish goes live (ISO 8601), in the future."}},"additionalProperties":false,"type":"object","required":["run_at"],"title":"PublishScheduleMove","description":"Move a queued publish to a new time."},"PublishTarget":{"properties":{"object":{"type":"string","const":"publish_target","title":"Object","default":"publish_target"},"id":{"type":"string","title":"Id","description":"Pass as `target_id` when publishing."},"type":{"type":"string","enum":["hosted_site","cms_connection"],"title":"Type","description":"`hosted_site` is the blog Rank Prompt hosts; `cms_connection` is the brand's own CMS."},"name":{"type":"string","title":"Name","description":"The site, as a person would name it."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"Where it lives."},"provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider","description":"The CMS behind it, e.g. `wordpress`."},"is_managed":{"type":"boolean","title":"Is Managed","description":"True when Rank Prompt runs the site itself.","default":false},"page_placement":{"type":"string","title":"Page Placement","description":"Where a page published with a path (a Website autopilot new page, such as a city page) lands: `path` at that very path (WordPress, the hosted blog, a GitHub repo whose pages were found), `top_level` at `/{last segment}/` (Ghost), `prefixed` under a prefix at the domain's root (Shopify `/pages/`, a Webflow or Wix connection's pages collection), `receiver` wherever the webhook receiver puts it (it gets `kind` and `path`), `post` as a blog post at the platform's own address. The set is open.","default":"post"},"default_status":{"anyOf":[{"type":"string","enum":["ask","draft"]},{"type":"null"}],"title":"Default Status","description":"What the brand's owner chose for every send to this site: `draft` when each article should land as a draft for someone to review, `ask` when it is chosen per publish. This API does not apply it for you: `publish_status` still defaults to `publish`, so send `publish_status: draft` when this says `draft`. Null for a provider without this choice (`github`, `webhook`) and for the hosted blog."},"settings":{"anyOf":[{"$ref":"#/components/schemas/CmsConnectionSettings"},{"type":"null"}],"description":"For a `cms_connection`, the owner's other publishing choices for its site, read only, as its CMS connection lists them. Null for the hosted blog."}},"additionalProperties":false,"type":"object","required":["id","type","name"],"title":"PublishTarget","description":"Somewhere this brand's articles can be published."},"PublishTargetList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/PublishTarget"},"type":"array","title":"Data"}},"additionalProperties":false,"type":"object","required":["data"],"title":"PublishTargetList","description":"Every target this brand can publish to, hosted blog first."},"QuotaResponse":{"properties":{"sku":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sku","description":"Standalone API SKU id (`api_starter`/`api_pro`) when a paid API subscription governs your quota; `null` when the monthly allowance on your plan does. Branch on `source` to disambiguate. (`null` here always means plan-included access, never 'no access'.)"},"source":{"type":"string","title":"Source","description":"Where the quota comes from: `sku` (a standalone API subscription) or `plan` (the monthly allowance on your plan, free included).","default":"sku"},"request_quota":{"$ref":"#/components/schemas/RequestQuota"},"current_period_end":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Current Period End","description":"Unix seconds when the period and quota reset."},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status","description":"Subscription status (`active`/`past_due`/…) for a SKU, or `plan` when the allowance on your plan meters you."}},"additionalProperties":false,"type":"object","required":["request_quota"],"title":"QuotaResponse","description":"Quota envelope for ``GET /v1/me/quota``.","example":{"current_period_end":1735689600,"request_quota":{"limit":200000,"remaining":195769,"used":4231},"sku":"api_pro","source":"sku","status":"active"}},"RankCheck":{"properties":{"id":{"type":"string","title":"Id"},"position":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Position"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"The brand's page at `position`; null when it did not rank or Google hid the page behind its own redirect."},"serp_features":{"items":{"type":"string"},"type":"array","title":"Serp Features"},"top_results":{"items":{"$ref":"#/components/schemas/SerpResult"},"type":"array","title":"Top Results","description":"Who held the top of the page."},"device":{"type":"string","const":"desktop","title":"Device","description":"Positions are checked on desktop.","default":"desktop"},"ai_overview_cites_brand":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Ai Overview Cites Brand","description":"The AI Overview cited a page on the brand's website at this check; null when the page had no overview, Google loaded it after the page, or the check predates it."},"ai_overview_names_brand":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Ai Overview Names Brand","description":"The AI Overview's text named the brand or one of its aliases at this check; null when there was no text or the check predates it."},"checked_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Checked At"}},"type":"object","required":["id"],"title":"RankCheck"},"RankChecksCreate":{"properties":{"keyword_ids":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":1000},{"type":"null"}],"title":"Keyword Ids"},"force":{"type":"boolean","title":"Force","description":"Also re-check keywords checked in the last 20 hours; otherwise those are skipped and not charged.","default":false}},"additionalProperties":false,"type":"object","title":"RankChecksCreate"},"RankChecksQueued":{"properties":{"object":{"type":"string","const":"rank_checks_queued","title":"Object","default":"rank_checks_queued"},"queued":{"type":"integer","title":"Queued","description":"Checks queued now. Positions land within minutes; read the keywords again."},"pending":{"type":"integer","title":"Pending","description":"Checks already queued before this call."},"skipped_fresh":{"type":"integer","title":"Skipped Fresh","description":"Keywords checked in the last 20 hours, left out."},"credits_charged":{"type":"integer","title":"Credits Charged"}},"type":"object","required":["queued","pending","skipped_fresh","credits_charged"],"title":"RankChecksQueued"},"RankSchedule":{"properties":{"object":{"type":"string","const":"rank_schedule","title":"Object","description":"Always `rank_schedule`.","default":"rank_schedule"},"frequency":{"type":"string","enum":["off","weekly","twice_weekly"],"title":"Frequency"},"next_run_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Next Run At","description":"When the next scheduled check starts."},"last_run_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Last Run At"},"paused_reason":{"anyOf":[{"type":"string","const":"credits"},{"type":"null"}],"title":"Paused Reason","description":"`credits`: a run found too few credits. Saving the schedule again resumes it."},"monthly_metrics_refresh":{"type":"boolean","title":"Monthly Metrics Refresh","description":"Also buy fresh volume and difficulty for the rank tracked keywords once a month.","default":false},"rank_tracked":{"type":"integer","minimum":0.0,"title":"Rank Tracked","description":"Keywords each run checks."},"credits_per_run":{"type":"integer","minimum":0.0,"title":"Credits Per Run","description":"At most, at today's rank tracked keywords: 1 credit per 10."},"weekly_credits":{"type":"integer","minimum":0.0,"title":"Weekly Credits","description":"`credits_per_run` times the runs a week."}},"type":"object","required":["frequency","rank_tracked","credits_per_run","weekly_credits"],"title":"RankSchedule","description":"The brand's scheduled rank checks: every rank tracked keyword, each run charged like `POST /keywords/rank-checks`."},"RankScheduleUpdate":{"properties":{"frequency":{"type":"string","enum":["off","weekly","twice_weekly"],"title":"Frequency"},"monthly_metrics_refresh":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Monthly Metrics Refresh","description":"Omit to keep the current setting."}},"type":"object","required":["frequency"],"title":"RankScheduleUpdate","description":"How often to check the rank tracked keywords on their own."},"RankedCandidate":{"properties":{"keyword":{"type":"string","title":"Keyword"},"position":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Position"},"search_volume":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Search Volume"},"keyword_difficulty":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Keyword Difficulty"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"}},"type":"object","required":["keyword"],"title":"RankedCandidate"},"RankedKeyword":{"properties":{"search_volume":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Search Volume","description":"Average monthly Google searches."},"cpc":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cpc","description":"Average cost per click, in USD."},"competition":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Competition","description":"Paid competition from 0 to 1."},"competition_level":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Competition Level","description":"`LOW`, `MEDIUM` or `HIGH`."},"keyword_difficulty":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Keyword Difficulty","description":"How hard it is to rank organically, 0 to 100."},"main_intent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Main Intent","description":"Search intent: informational, navigational, commercial or transactional."},"trend":{"anyOf":[{"$ref":"#/components/schemas/KeywordTrend"},{"type":"null"}]},"monthly_searches":{"anyOf":[{"items":{"$ref":"#/components/schemas/MonthlySearches"},"type":"array"},{"type":"null"}],"title":"Monthly Searches","description":"The last months' volume."},"serp_item_types":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Serp Item Types","description":"What Google shows on the results page."},"has_ai_overview":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Ai Overview","description":"Google answers this keyword with an AI Overview. Null where the results page was not bought, which is the case on the keyword gap and on ranked keywords."},"fetched_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Fetched At","description":"When these numbers were bought."},"keyword":{"type":"string","title":"Keyword"},"position":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Position"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"},"etv":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Etv","description":"Estimated monthly traffic from this keyword."},"is_featured_snippet":{"type":"boolean","title":"Is Featured Snippet","default":false},"tracked":{"type":"boolean","title":"Tracked","default":false}},"type":"object","required":["keyword"],"title":"RankedKeyword"},"RegionChange":{"properties":{"delta":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Delta","description":"Change in points over the shared answers; null when they share none."},"same":{"type":"boolean","title":"Same","description":"True when both runs asked exactly the same answers."},"shared_answers":{"type":"integer","minimum":0.0,"title":"Shared Answers","description":"Answers both runs asked."},"new_prompts":{"type":"integer","minimum":0.0,"title":"New Prompts","description":"Prompts only the newer run asked, left out of the delta."},"dropped_prompts":{"type":"integer","minimum":0.0,"title":"Dropped Prompts","description":"Prompts only the older run asked, left out of the delta."},"region_config_id":{"type":"string","title":"Region Config Id"}},"additionalProperties":false,"type":"object","required":["same","shared_answers","new_prompts","dropped_prompts","region_config_id"],"title":"RegionChange","description":"One region config's latest run against its run before."},"RegionConfig":{"properties":{"object":{"type":"string","title":"Object","description":"Always `region_config`.","default":"region_config"},"id":{"type":"string","title":"Id","description":"Stable region-config identifier (UUID)."},"brand_id":{"type":"string","title":"Brand Id","description":"Owning brand id (UUID)."},"name":{"type":"string","title":"Name","description":"Human-readable label (e.g. `United States, English`)."},"country":{"type":"string","title":"Country","description":"Country the region targets."},"location":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location","description":"Free-form location string used for queries."},"language":{"type":"string","title":"Language","description":"Language label (e.g. `English`, `Spanish`)."},"ai_platforms":{"items":{"type":"string"},"type":"array","title":"Ai Platforms","description":"AI platforms this region runs against, as it runs them today: a retired engine reads as the one that replaced it, so the list can be sent back as is. Each prompt costs 1 credit per 3 engines, rounded up: 1 to 3 engines cost 1 credit, 4 to 6 cost 2, all 7 cost 3."},"is_active":{"type":"boolean","title":"Is Active","description":"Whether the config is used by scheduled runs."},"scheduled_report_id":{"type":"string","title":"Scheduled Report Id","description":"Schedule this config feeds. Required: every region config is tied to exactly one schedule (DB column is `NOT NULL`)."},"source_report_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Report Id","description":"Always null: a region config is a market of its scheduled report and keeps no source report."},"prompts_count":{"type":"integer","minimum":0.0,"title":"Prompts Count","description":"Active prompts this region config asks: its own and the ones every region config shares.","default":0},"last_run_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Last Run At","description":"ISO-8601 timestamp of the most recent scheduled run from this config."},"last_run_status":{"anyOf":[{"type":"string","enum":["processing","completed","failed"]},{"type":"null"}],"title":"Last Run Status","description":"Status of the most recent run."},"last_error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Error Message","description":"Last error message surfaced by a scheduled run, if any."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"ISO-8601 timestamp when the region config was created."},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Updated At","description":"ISO-8601 timestamp of the last update to the region config."}},"additionalProperties":false,"type":"object","required":["id","brand_id","name","country","language","is_active","scheduled_report_id","created_at"],"title":"RegionConfig","description":"A region config: reusable bundle of country/language/platforms for a brand.","example":{"ai_platforms":["chatgpt","claude","ai_overviews"],"brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","country":"United States","created_at":"2026-04-01T11:00:00+00:00","id":"018e7c2e-33ab-7df1-b1cd-2ac3a8f9112d","is_active":true,"language":"English","last_run_at":"2026-04-19T03:00:00+00:00","last_run_status":"completed","location":"New York, NY","name":"United States, English","object":"region_config","prompts_count":12,"scheduled_report_id":"018e7c2d-33ab-7df1-b1cd-2ac3a8f9112d","updated_at":"2026-04-19T03:00:00+00:00"}},"RegionConfigCreate":{"properties":{"brand_id":{"type":"string","title":"Brand Id","description":"Brand to create the region config under."},"name":{"type":"string","maxLength":200,"minLength":1,"title":"Name","description":"Human-readable label."},"country":{"type":"string","maxLength":100,"minLength":1,"title":"Country","description":"Country the region targets."},"location":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Location","description":"Optional sub-region / city."},"language":{"type":"string","maxLength":50,"title":"Language","description":"Language. Accepts English name (`English`, `Spanish`) or ISO 639-1 code (`en`, `es`).","default":"English"},"ai_platforms":{"items":{"type":"string","enum":["chatgpt","claude","ai_overviews","grok","perplexity","gemini","muse"]},"type":"array","maxItems":10,"minItems":1,"title":"Ai Platforms","description":"AI platforms to run against (1-10). Engines: `chatgpt`, `claude`, `ai_overviews`, `grok`, `perplexity`, `gemini`, `muse`. Each prompt costs 1 credit per 3 engines, rounded up: 1 to 3 engines cost 1 credit, 4 to 6 cost 2, all 7 cost 3. Any other value, retired ones included (`chatgpt_search`, `claude_search`), answers `ai_platform_unsupported`. Defaults to `[\"chatgpt\", \"claude\", \"ai_overviews\"]`."},"scheduled_report_id":{"type":"string","title":"Scheduled Report Id","description":"Schedule to attach this region config to. Required. Create the schedule first via `POST /v1/scheduled-reports`, then pass its id here."},"source_report_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Report Id","description":"Optionally bootstrap the config from an existing report's settings."},"is_active":{"type":"boolean","title":"Is Active","description":"Whether the config should run on scheduled executions.","default":true},"copy_report_prompts":{"type":"boolean","title":"Copy Report Prompts","description":"Seed the new config with the prompts of `source_report_id`, in the same call. A report with no prompts to copy leaves the config paused (`is_active: false`) instead of waking a schedule that would run nothing.","default":false}},"additionalProperties":false,"type":"object","required":["brand_id","name","country","scheduled_report_id"],"title":"RegionConfigCreate","description":"Request body for ``POST /v1/region-configs``.","example":{"ai_platforms":["chatgpt","claude","ai_overviews"],"brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","country":"United States","is_active":true,"language":"English","location":"New York, NY","name":"United States, English","scheduled_report_id":"018e7c2d-33ab-7df1-b1cd-2ac3a8f9112d"}},"RegionConfigList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/RegionConfig"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Opaque continuation token. Pass back as `?cursor=` to fetch the next page. `null` when `has_more` is false."}},"additionalProperties":false,"type":"object","required":["data","has_more"],"title":"RegionConfigList","description":"Cursor-paginated list of region configs (top-level ``GET /v1/region-configs``).","example":{"data":[{"ai_platforms":["chatgpt","claude","ai_overviews"],"brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","country":"United States","created_at":"2026-04-01T11:00:00+00:00","id":"018e7c2e-33ab-7df1-b1cd-2ac3a8f9112d","is_active":true,"language":"English","last_run_at":"2026-04-19T03:00:00+00:00","last_run_status":"completed","location":"New York, NY","name":"United States, English","object":"region_config","prompts_count":12,"scheduled_report_id":"018e7c2d-33ab-7df1-b1cd-2ac3a8f9112d","updated_at":"2026-04-19T03:00:00+00:00"}],"has_more":false,"object":"list"}},"RegionConfigPrompt":{"properties":{"object":{"type":"string","title":"Object","description":"Always `region_config_prompt`.","default":"region_config_prompt"},"id":{"type":"string","title":"Id","description":"Stable identifier (UUID)."},"region_config_id":{"type":"string","title":"Region Config Id","description":"Owning region config id (UUID)."},"prompt_text":{"type":"string","title":"Prompt Text","description":"The prompt text as stored. `{city}` in it stands for the city of each region config that asks it."},"category":{"type":"string","title":"Category","description":"Free-form taxonomy bucket. Used to group prompts in schedule analytics."},"intent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Intent","description":"The prompt's funnel intent: `awareness` (learning about a topic), `consideration` (weighing options) or `decision` (choosing between named options); `null` when unclassified. Written with generated prompts, set by hand otherwise. An open set."},"disabled":{"type":"boolean","title":"Disabled","description":"Whether the prompt is excluded from scheduled runs."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"ISO-8601 timestamp."},"rendered_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rendered Text","description":"What this region config asks: `prompt_text` with `{city}` replaced by its city, in the region config's language when it differs from the report's (a translation of the same tracked prompt)."},"shared":{"type":"boolean","title":"Shared","description":"`true` when every region config of the scheduled report asks this prompt: editing, pausing or deleting it here changes it in all of them.","default":false}},"additionalProperties":false,"type":"object","required":["id","region_config_id","prompt_text","category","disabled","created_at"],"title":"RegionConfigPrompt","description":"A prompt attached to a region config.","example":{"category":"CRM Software","created_at":"2026-04-01T11:00:00+00:00","disabled":false,"id":"018e7c2f-33ab-7df1-b1cd-2ac3a8f9112d","intent":"consideration","object":"region_config_prompt","prompt_text":"best CRM for startups","region_config_id":"018e7c2e-33ab-7df1-b1cd-2ac3a8f9112d","rendered_text":"best CRM for startups","shared":false}},"RegionConfigPromptBulkCreate":{"properties":{"prompts":{"items":{"$ref":"#/components/schemas/RegionConfigPromptInput"},"type":"array","maxItems":50,"minItems":1,"title":"Prompts","description":"Up to 50 prompts to add. Adding the first prompt to an inactive config auto-reactivates it."}},"additionalProperties":false,"type":"object","required":["prompts"],"title":"RegionConfigPromptBulkCreate","description":"Request body for ``POST /v1/region-configs/{id}/prompts``."},"RegionConfigPromptBulkCreated":{"properties":{"object":{"type":"string","title":"Object","description":"Always `list`.","default":"list"},"data":{"items":{"$ref":"#/components/schemas/RegionConfigPrompt"},"type":"array","title":"Data","description":"The freshly created prompts."}},"additionalProperties":false,"type":"object","required":["data"],"title":"RegionConfigPromptBulkCreated","description":"Response envelope for prompt bulk-create."},"RegionConfigPromptInput":{"properties":{"prompt_text":{"type":"string","maxLength":1000,"minLength":1,"title":"Prompt Text","description":"The prompt text to evaluate against the AI platforms."},"category":{"type":"string","maxLength":100,"minLength":1,"title":"Category","description":"Free-form taxonomy bucket. Use a stable string per bucket; this is what powers per-category breakdowns in schedule analytics."},"intent":{"anyOf":[{"type":"string","enum":["awareness","consideration","decision"]},{"type":"null"}],"title":"Intent","description":"Optional funnel intent: `awareness`, `consideration` or `decision`. Left out, the prompt stays unclassified."}},"additionalProperties":false,"type":"object","required":["prompt_text","category"],"title":"RegionConfigPromptInput","description":"One prompt in a bulk-create request."},"RegionConfigPromptList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/RegionConfigPrompt"},"type":"array","title":"Data"}},"additionalProperties":false,"type":"object","required":["data"],"title":"RegionConfigPromptList","description":"List of region config prompts.","example":{"data":[{"category":"CRM Software","created_at":"2026-04-01T11:00:00+00:00","disabled":false,"id":"018e7c2f-33ab-7df1-b1cd-2ac3a8f9112d","intent":"consideration","object":"region_config_prompt","prompt_text":"best CRM for startups","region_config_id":"018e7c2e-33ab-7df1-b1cd-2ac3a8f9112d","rendered_text":"best CRM for startups","shared":false}],"object":"list"}},"RegionConfigPromptUpdate":{"properties":{"prompt_text":{"anyOf":[{"type":"string","maxLength":1000,"minLength":1},{"type":"null"}],"title":"Prompt Text"},"category":{"anyOf":[{"type":"string","maxLength":100,"minLength":1},{"type":"null"}],"title":"Category"},"intent":{"anyOf":[{"type":"string","enum":["awareness","consideration","decision"]},{"type":"null"}],"title":"Intent","description":"New funnel intent: `awareness`, `consideration` or `decision`; `null` makes it unclassified."},"disabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Disabled"},"mode":{"type":"string","enum":["reword","new_question"],"title":"Mode","description":"How a new `prompt_text` is read. `reword` (default) keeps the prompt and its history: the same question said better. `new_question` pauses this prompt and returns a new one (a new id) whose history starts over.","default":"reword"}},"additionalProperties":false,"type":"object","title":"RegionConfigPromptUpdate","description":"Partial-update body for a region config prompt."},"RegionConfigUpdate":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":200,"minLength":1},{"type":"null"}],"title":"Name"},"country":{"anyOf":[{"type":"string","maxLength":100,"minLength":1},{"type":"null"}],"title":"Country"},"location":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Location"},"language":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"title":"Language"},"ai_platforms":{"anyOf":[{"items":{"type":"string","enum":["chatgpt","claude","ai_overviews","grok","perplexity","gemini","muse"]},"type":"array","maxItems":10,"minItems":1},{"type":"null"}],"title":"Ai Platforms","description":"AI platforms to run against. Engines: `chatgpt`, `claude`, `ai_overviews`, `grok`, `perplexity`, `gemini`, `muse`. Each prompt costs 1 credit per 3 engines, rounded up: 1 to 3 engines cost 1 credit, 4 to 6 cost 2, all 7 cost 3. Any other value, retired ones included (`chatgpt_search`, `claude_search`), answers `ai_platform_unsupported`."},"is_active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Active"}},"additionalProperties":false,"type":"object","title":"RegionConfigUpdate","description":"Partial-update body for ``PATCH /v1/region-configs/{id}``."},"Report":{"properties":{"object":{"type":"string","title":"Object","description":"Always `report`.","default":"report"},"id":{"type":"string","title":"Id","description":"Stable report identifier (UUID)."},"brand_id":{"type":"string","title":"Brand Id","description":"Owning brand id (UUID)."},"name":{"type":"string","title":"Name","description":"Human-readable report label (defaults to `Untitled Report`)."},"status":{"type":"string","enum":["draft","processing","completed","failed"],"title":"Status","description":"Report lifecycle status."},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country","description":"Country the report was scoped to."},"location":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location","description":"Free-form location string used for queries."},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language","description":"Primary language (English name like `English`, `Spanish`)."},"ai_platforms":{"items":{"type":"string"},"type":"array","title":"Ai Platforms","description":"AI platforms the report runs against. An open set: results recorded before an engine was retired keep it (`chatgpt_search`, `claude_search`). Each prompt costs 1 credit per 3 engines, rounded up: 1 to 3 engines cost 1 credit, 4 to 6 cost 2, all 7 cost 3."},"visibility_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Visibility Score","description":"Aggregate brand visibility score (0-100). Null until the report completes."},"total_results":{"type":"integer","minimum":0.0,"title":"Total Results","description":"Total prompt-platform results materialised by the run","default":0},"ranked_prompts":{"type":"integer","minimum":0.0,"title":"Ranked Prompts","description":"Prompt-platform results that surfaced the brand. Always ≤ `total_results`.","default":0},"scheduled_report_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scheduled Report Id","description":"The scheduled report this report is a run of; null for a one-off report. A manual run of a schedule (`POST /v1/scheduled-reports/{id}/executions`) carries it too."},"region_config_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Region Config Id","description":"The region config of the scheduled report this report ran for; null for a one-off report."},"batch_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Batch Id","description":"The scheduled run this report belongs to, shared by the reports of that run; null for a one-off."},"tracker_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tracker Id","description":"The tracker (the report's definition: its markets, prompts and engines) this report is a result of. Equals `scheduled_report_id` for a scheduled report and `id` for a one-off report's first run."},"run_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run Id","description":"The run this report is the result of (one report per market and run); null for a draft."},"market_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Market Id","description":"The market (country, city and language) this report measured; equals `region_config_id` when set."},"failure_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Failure Reason","description":"Human-readable reason when `status == 'failed'`."},"degraded_cells_count":{"type":"integer","minimum":0.0,"title":"Degraded Cells Count","description":"Cells that returned degraded/partial data in this report.","default":0},"cells_permanently_failed":{"type":"integer","minimum":0.0,"title":"Cells Permanently Failed","description":"Cells that permanently failed after retries.","default":0},"build_phase":{"anyOf":[{"type":"string","enum":["queued","answering","resolving","finishing"]},{"type":"null"}],"title":"Build Phase","description":"Where a running report is: `queued`, `answering` (the engines answer), `resolving` (the businesses the answers name are resolved) or `finishing`; null when it is not running."},"progress":{"anyOf":[{"$ref":"#/components/schemas/ReportProgress"},{"type":"null"}],"description":"Cells answered and failed while the report runs; null when it is not running."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"ISO-8601 timestamp when the report was created."}},"additionalProperties":false,"type":"object","required":["id","brand_id","name","status","created_at"],"title":"Report","description":"A report.","example":{"ai_platforms":["chatgpt","claude","ai_overviews"],"brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","cells_permanently_failed":0,"country":"United States","created_at":"2024-09-01T11:00:00+00:00","degraded_cells_count":0,"id":"8a72d9f1-c4b5-4e6d-9b1f-0e3a2c6d8b04","language":"en","location":"United States","market_id":"8a72d9f1-c4b5-4e6d-9b1f-0e3a2c6d8b04","name":"adidas weekly visibility, Sept 2024","object":"report","ranked_prompts":17,"run_id":"8a72d9f1-c4b5-4e6d-9b1f-0e3a2c6d8b04","status":"completed","total_results":60,"tracker_id":"8a72d9f1-c4b5-4e6d-9b1f-0e3a2c6d8b04","visibility_score":42.7}},"ReportAiAnalysis":{"properties":{"object":{"type":"string","title":"Object","description":"Always `report_ai_analysis`.","default":"report_ai_analysis"},"report_id":{"type":"string","title":"Report Id","description":"The report this analysis belongs to (UUID)."},"ai_suggestion":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ai Suggestion","description":"Human-readable recommendation written by the LLM. `null` until the AI-suggestion step has been triggered for this report."},"ai_analysis":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Ai Analysis","description":"Structured companion to `ai_suggestion` (categories, trends, highlights, etc.)."},"generated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Generated At","description":"ISO-8601 timestamp the analysis was last refreshed. Falls back to the report's `created_at` while the analysis is `null`."}},"additionalProperties":false,"type":"object","required":["report_id"],"title":"ReportAiAnalysis","description":"LLM-authored commentary on a completed report.","example":{"ai_analysis":{"highlights":[{"category":"Trail Running","trend":"down"},{"category":"Running Shoes","trend":"up"}],"summary":"Brand visibility is improving on Running Shoes queries."},"ai_suggestion":"Visibility on ChatGPT improved by 12 points week-over-week, mostly driven by `Running Shoes` prompts. `Trail Running` still trails competitors. Consider publishing a head-to-head comparison page targeting that topic.","generated_at":"2024-09-01T11:42:11.117+00:00","object":"report_ai_analysis","report_id":"8a72d9f1-c4b5-4e6d-9b1f-0e3a2c6d8b04"}},"ReportCompetitor":{"properties":{"object":{"type":"string","const":"report_competitor","title":"Object","description":"Always `report_competitor`.","default":"report_competitor"},"name":{"type":"string","title":"Name","description":"The name the registry keeps; an alias counts under its competitor."},"mentions":{"type":"integer","minimum":0.0,"title":"Mentions","description":"Answers that named it."},"category":{"type":"string","title":"Category","description":"Its relation to the brand: `direct_competitor`, `indirect_competitor`, `ai_platform`, `publisher`, `my_brand` or `other`."},"website":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Website","description":"Its website, when known."},"platforms":{"additionalProperties":{"type":"integer"},"type":"object","title":"Platforms","description":"Mentions per AI platform."},"significant":{"type":"boolean","title":"Significant","description":"Part of the head of the ranking: at least three, cut where mentions drop by half or 80 percent is reached."}},"additionalProperties":false,"type":"object","required":["name","mentions","category","platforms","significant"],"title":"ReportCompetitor","description":"One business the report's answers named, with how often and on which engines."},"ReportCompetitorList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/ReportCompetitor"},"type":"array","title":"Data"},"report_id":{"type":"string","title":"Report Id","description":"The report read."}},"additionalProperties":false,"type":"object","required":["data","report_id"],"title":"ReportCompetitorList","description":"Every business a report named, most mentioned first.","example":{"data":[{"category":"direct_competitor","mentions":14,"name":"HubSpot","object":"report_competitor","platforms":{"chatgpt":6,"gemini":3,"perplexity":5},"significant":true,"website":"https://www.hubspot.com"}],"object":"list","report_id":"c4f8b6a2-9a17-4e31-92fa-7d1e3b5c8b2a"}},"ReportCreate":{"properties":{"brand_id":{"type":"string","title":"Brand Id","description":"Brand to attach the report to (UUID)."},"name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Name","description":"Optional human-readable report name. Defaults to `<brand_name> Report`."},"country":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Country","description":"Country the report targets."},"location":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Location","description":"Free-form location used to scope queries, e.g. `New York, NY` or `California`. More specific than `country`."},"language":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"title":"Language","description":"Primary language. Accepts English name (`English`) or ISO 639-1 code (`en`)."},"ai_platforms":{"anyOf":[{"items":{"type":"string","enum":["chatgpt","claude","ai_overviews","grok","perplexity","gemini","muse"]},"type":"array","maxItems":10},{"type":"null"}],"title":"Ai Platforms","description":"AI platforms to query. Engines: `chatgpt`, `claude`, `ai_overviews`, `grok`, `perplexity`, `gemini`, `muse`. Each prompt costs 1 credit per 3 engines, rounded up: 1 to 3 engines cost 1 credit, 4 to 6 cost 2, all 7 cost 3. Any other value, retired ones included (`chatgpt_search`, `claude_search`), answers `ai_platform_unsupported`. Defaults to `[\"chatgpt\", \"claude\", \"ai_overviews\"]`, or to the region config's engines when `region_config_id` is set (a retired engine there runs as its replacement)."},"region_config_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Region Config Id","description":"Optional region config to copy the market from (UUID): any of `country`, `location`, `language` and `ai_platforms` you leave out comes from it. The report is a one-off copy and does not join the scheduled report's runs, so its `region_config_id` reads null."}},"additionalProperties":false,"type":"object","required":["brand_id"],"title":"ReportCreate","description":"Body for ``POST /v1/reports``. Creates a draft; trigger analysis with `POST /reports/{id}/runs`.","examples":[{"ai_platforms":["chatgpt","claude","ai_overviews"],"brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","country":"United States","language":"English","name":"Q4 launch visibility"}]},"ReportDetail":{"properties":{"object":{"type":"string","title":"Object","description":"Always `report`.","default":"report"},"id":{"type":"string","title":"Id","description":"Stable report identifier (UUID)."},"brand_id":{"type":"string","title":"Brand Id","description":"Owning brand id (UUID)."},"name":{"type":"string","title":"Name","description":"Human-readable report label (defaults to `Untitled Report`)."},"status":{"type":"string","enum":["draft","processing","completed","failed"],"title":"Status","description":"Report lifecycle status."},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country","description":"Country the report was scoped to."},"location":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location","description":"Free-form location string used for queries."},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language","description":"Primary language (English name like `English`, `Spanish`)."},"ai_platforms":{"items":{"type":"string"},"type":"array","title":"Ai Platforms","description":"AI platforms the report runs against. An open set: results recorded before an engine was retired keep it (`chatgpt_search`, `claude_search`). Each prompt costs 1 credit per 3 engines, rounded up: 1 to 3 engines cost 1 credit, 4 to 6 cost 2, all 7 cost 3."},"visibility_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Visibility Score","description":"Aggregate brand visibility score (0-100). Null until the report completes."},"total_results":{"type":"integer","minimum":0.0,"title":"Total Results","description":"Total prompt-platform results materialised by the run","default":0},"ranked_prompts":{"type":"integer","minimum":0.0,"title":"Ranked Prompts","description":"Prompt-platform results that surfaced the brand. Always ≤ `total_results`.","default":0},"scheduled_report_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scheduled Report Id","description":"The scheduled report this report is a run of; null for a one-off report. A manual run of a schedule (`POST /v1/scheduled-reports/{id}/executions`) carries it too."},"region_config_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Region Config Id","description":"The region config of the scheduled report this report ran for; null for a one-off report."},"batch_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Batch Id","description":"The scheduled run this report belongs to, shared by the reports of that run; null for a one-off."},"tracker_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tracker Id","description":"The tracker (the report's definition: its markets, prompts and engines) this report is a result of. Equals `scheduled_report_id` for a scheduled report and `id` for a one-off report's first run."},"run_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run Id","description":"The run this report is the result of (one report per market and run); null for a draft."},"market_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Market Id","description":"The market (country, city and language) this report measured; equals `region_config_id` when set."},"failure_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Failure Reason","description":"Human-readable reason when `status == 'failed'`."},"degraded_cells_count":{"type":"integer","minimum":0.0,"title":"Degraded Cells Count","description":"Cells that returned degraded/partial data in this report.","default":0},"cells_permanently_failed":{"type":"integer","minimum":0.0,"title":"Cells Permanently Failed","description":"Cells that permanently failed after retries.","default":0},"build_phase":{"anyOf":[{"type":"string","enum":["queued","answering","resolving","finishing"]},{"type":"null"}],"title":"Build Phase","description":"Where a running report is: `queued`, `answering` (the engines answer), `resolving` (the businesses the answers name are resolved) or `finishing`; null when it is not running."},"progress":{"anyOf":[{"$ref":"#/components/schemas/ReportProgress"},{"type":"null"}],"description":"Cells answered and failed while the report runs; null when it is not running."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"ISO-8601 timestamp when the report was created."},"prompts":{"items":{"$ref":"#/components/schemas/ReportDetailPrompt"},"type":"array","title":"Prompts","description":"Every prompt attached to the report (capped at `MAX_PROMPTS_PER_REPORT = 50`), each with its per-platform results inlined under `results`."}},"additionalProperties":false,"type":"object","required":["id","brand_id","name","status","created_at"],"title":"ReportDetail","description":"Single-report read shape (`GET /v1/reports/{id}`).","example":{"ai_platforms":["chatgpt","claude","ai_overviews"],"brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","cells_permanently_failed":0,"country":"United States","created_at":"2024-09-01T11:00:00+00:00","degraded_cells_count":0,"id":"8a72d9f1-c4b5-4e6d-9b1f-0e3a2c6d8b04","language":"en","location":"United States","market_id":"8a72d9f1-c4b5-4e6d-9b1f-0e3a2c6d8b04","name":"adidas weekly visibility, Sept 2024","object":"report","prompts":[{"brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","category":"Running Shoes","created_at":"2026-04-01T11:00:00+00:00","id":"018e7c2c-33ab-7df1-b1cd-2ac3a8f9112d","object":"prompt","prompt_text":"What are the best running shoes for a first marathon?","report_id":"8a72d9f1-c4b5-4e6d-9b1f-0e3a2c6d8b04","results":[{"ai_platform":"chatgpt","brand_appears":true,"businesses_categorized":[{"category":"direct_competitor","mentioned_as":"Asics","name":"ASICS","object":"business_categorized","reason":"Running shoe brand frequently cited alongside the brand."},{"category":"indirect_competitor","name":"Brooks Running","object":"business_categorized","reason":"Running shoe brand mentioned in the same answer."}],"citations":[{"object":"citation","snippet":"The adidas Adizero Boston 12 earns high marks as a marathon trainer...","source_name":"Runner's World","title":"The Best Running Shoes of 2026","url":"https://www.runnersworld.com/gear/a20865766/best-running-shoes/"},{"object":"citation","title":"The Best Running Shoes","url":"https://www.nytimes.com/wirecutter/reviews/best-running-shoes/"}],"created_at":"2026-04-01T11:42:11.117+00:00","id":"018e7c30-33ab-7df1-b1cd-2ac3a8f9112d","model_version":"gpt-6-luna","object":"report_result","prompt_id":"018e7c2c-33ab-7df1-b1cd-2ac3a8f9112d","rank":2,"response":"For a first marathon, the adidas Adizero Boston 12 is frequently recommended alongside ..."}]}],"ranked_prompts":17,"run_id":"8a72d9f1-c4b5-4e6d-9b1f-0e3a2c6d8b04","status":"completed","total_results":60,"tracker_id":"8a72d9f1-c4b5-4e6d-9b1f-0e3a2c6d8b04","visibility_score":42.7}},"ReportDetailPrompt":{"properties":{"object":{"type":"string","title":"Object","description":"Always `prompt`.","default":"prompt"},"id":{"type":"string","title":"Id","description":"Stable prompt identifier (UUID)."},"brand_id":{"type":"string","title":"Brand Id","description":"Owning brand id (UUID)."},"report_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Report Id","description":"Report this prompt belongs to."},"prompt_text":{"type":"string","title":"Prompt Text","description":"The natural-language query sent to the AI platforms."},"category":{"type":"string","title":"Category","description":"Free-form taxonomy bucket. Used to group prompts in analytics surfaces."},"intent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Intent","description":"The prompt's funnel intent: `awareness` (learning about a topic), `consideration` (weighing options) or `decision` (choosing between named options); `null` when unclassified. Written with generated prompts, set by hand otherwise. An open set."},"region_config_prompt_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Region Config Prompt Id","description":"The tracked prompt this prompt was asked from, the same id in every run and market that asks it (a region config prompt's id for a scheduled report). Null only for prompts older than tracking."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"ISO-8601 timestamp when the prompt was created."},"results":{"items":{"$ref":"#/components/schemas/ReportResult"},"type":"array","title":"Results","description":"Per-platform results for this prompt. Empty while the report is `draft`/`processing`; populated after analysis completes."}},"additionalProperties":false,"type":"object","required":["id","brand_id","prompt_text","category","created_at"],"title":"ReportDetailPrompt","description":"A prompt nested inside `ReportDetail`, with its results inline.","example":{"brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","category":"Running Shoes","created_at":"2026-04-01T11:00:00+00:00","id":"018e7c2c-33ab-7df1-b1cd-2ac3a8f9112d","object":"prompt","prompt_text":"What are the best running shoes for a first marathon?","report_id":"8a72d9f1-c4b5-4e6d-9b1f-0e3a2c6d8b04","results":[{"ai_platform":"chatgpt","brand_appears":true,"businesses_categorized":[{"category":"direct_competitor","mentioned_as":"Asics","name":"ASICS","object":"business_categorized","reason":"Running shoe brand frequently cited alongside the brand."},{"category":"indirect_competitor","name":"Brooks Running","object":"business_categorized","reason":"Running shoe brand mentioned in the same answer."}],"citations":[{"object":"citation","snippet":"The adidas Adizero Boston 12 earns high marks as a marathon trainer...","source_name":"Runner's World","title":"The Best Running Shoes of 2026","url":"https://www.runnersworld.com/gear/a20865766/best-running-shoes/"},{"object":"citation","title":"The Best Running Shoes","url":"https://www.nytimes.com/wirecutter/reviews/best-running-shoes/"}],"created_at":"2026-04-01T11:42:11.117+00:00","id":"018e7c30-33ab-7df1-b1cd-2ac3a8f9112d","model_version":"gpt-6-luna","object":"report_result","prompt_id":"018e7c2c-33ab-7df1-b1cd-2ac3a8f9112d","rank":2,"response":"For a first marathon, the adidas Adizero Boston 12 is frequently recommended alongside ..."}]}},"ReportList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/Report"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Opaque continuation token. Pass back as `?cursor=` to fetch the next page. `null` when `has_more` is false."}},"additionalProperties":false,"type":"object","required":["data","has_more"],"title":"ReportList","description":"Cursor-paginated list of reports.","example":{"data":[{"ai_platforms":["chatgpt","claude","ai_overviews"],"brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","cells_permanently_failed":0,"country":"United States","created_at":"2024-09-01T11:00:00+00:00","degraded_cells_count":0,"id":"8a72d9f1-c4b5-4e6d-9b1f-0e3a2c6d8b04","language":"en","location":"United States","market_id":"8a72d9f1-c4b5-4e6d-9b1f-0e3a2c6d8b04","name":"adidas weekly visibility, Sept 2024","object":"report","ranked_prompts":17,"run_id":"8a72d9f1-c4b5-4e6d-9b1f-0e3a2c6d8b04","status":"completed","total_results":60,"tracker_id":"8a72d9f1-c4b5-4e6d-9b1f-0e3a2c6d8b04","visibility_score":42.7}],"has_more":false,"object":"list"}},"ReportProgress":{"properties":{"cells_total":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Cells Total","description":"Cells the run asks; null until it is planned."},"cells_answered":{"type":"integer","minimum":0.0,"title":"Cells Answered","description":"Cells answered so far.","default":0},"cells_failed":{"type":"integer","minimum":0.0,"title":"Cells Failed","description":"Cells that failed so far.","default":0}},"additionalProperties":false,"type":"object","title":"ReportProgress","description":"How far a running report has got: the prompt and engine cells it asks, answered and failed so far."},"ReportResult":{"properties":{"object":{"type":"string","title":"Object","description":"Always `report_result`.","default":"report_result"},"id":{"type":"string","title":"Id","description":"Stable result identifier (UUID)."},"prompt_id":{"type":"string","title":"Prompt Id","description":"Owning prompt id (UUID)."},"ai_platform":{"type":"string","title":"Ai Platform","description":"AI platform that produced this answer (e.g. `chatgpt`)."},"model_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model Version","description":"Model that produced this answer (e.g. `gpt-6-luna`), kept per answer so a model change shows in the data. Null only for answers recorded before this was tracked."},"brand_appears":{"type":"boolean","title":"Brand Appears","description":"Whether the brand was mentioned in the answer."},"rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rank","description":"Brand rank within the answer. Null when not mentioned or no ranked list."},"response":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response","description":"Raw natural-language answer returned by the AI platform."},"citations":{"items":{"$ref":"#/components/schemas/ReportCitation"},"type":"array","title":"Citations","description":"The pages the answer cites, each with the URL plus any title/snippet/source/favicon/thumbnail/grounding-span metadata the provider returned. Pages it only read are in `retrieved`."},"retrieved":{"items":{"$ref":"#/components/schemas/ReportCitation"},"type":"array","title":"Retrieved","description":"Pages the engine read while answering (search results, pages it opened) that its text does not cite; never in `citations`. Filled for ChatGPT, Claude, Gemini, Grok and Muse; empty for Perplexity and Google AI Mode, whose sources are all cited, and for answers recorded before it was kept. Claude, Gemini and Grok answers recorded before 2026-10-29 list these pages in `citations` too."},"fanouts":{"items":{"type":"string"},"type":"array","title":"Fanouts","description":"The web searches the engine ran to write this answer (fan-outs), in its order. Filled for ChatGPT, Claude, Gemini, Grok, Perplexity and Muse; empty for Google AI Mode, which does not report them."},"businesses_categorized":{"items":{"$ref":"#/components/schemas/BusinessCategorized"},"type":"array","title":"Businesses Categorized","description":"Other businesses mentioned in the same answer, with LLM-assigned category and rationale."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"ISO-8601 timestamp when the result was recorded."}},"additionalProperties":false,"type":"object","required":["id","prompt_id","ai_platform","brand_appears","created_at"],"title":"ReportResult","description":"One per-platform result for a prompt within a report.","example":{"ai_platform":"chatgpt","brand_appears":true,"businesses_categorized":[{"category":"direct_competitor","mentioned_as":"Asics","name":"ASICS","object":"business_categorized","reason":"Running shoe brand frequently cited alongside the brand."},{"category":"indirect_competitor","name":"Brooks Running","object":"business_categorized","reason":"Running shoe brand mentioned in the same answer."}],"citations":[{"object":"citation","snippet":"The adidas Adizero Boston 12 earns high marks as a marathon trainer...","source_name":"Runner's World","title":"The Best Running Shoes of 2026","url":"https://www.runnersworld.com/gear/a20865766/best-running-shoes/"},{"object":"citation","title":"The Best Running Shoes","url":"https://www.nytimes.com/wirecutter/reviews/best-running-shoes/"}],"created_at":"2026-04-01T11:42:11.117+00:00","id":"018e7c30-33ab-7df1-b1cd-2ac3a8f9112d","model_version":"gpt-6-luna","object":"report_result","prompt_id":"018e7c2c-33ab-7df1-b1cd-2ac3a8f9112d","rank":2,"response":"For a first marathon, the adidas Adizero Boston 12 is frequently recommended alongside ..."}},"ReportRun":{"properties":{},"additionalProperties":false,"type":"object","title":"ReportRun","description":"Body for ``POST /v1/reports/{id}/runs``."},"ReportRunDispatched":{"properties":{"object":{"type":"string","title":"Object","description":"Always `report.run`.","default":"report.run"},"report_id":{"type":"string","title":"Report Id","description":"The report being analyzed (UUID)."},"job_id":{"type":"string","title":"Job Id","description":"Async job id; poll via `GET /v1/jobs/{job_id}`."},"run_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run Id","description":"The run started (or retried) for the report."}},"additionalProperties":false,"type":"object","required":["report_id","job_id"],"title":"ReportRunDispatched","description":"202 envelope from ``POST /v1/reports/{id}/runs``.","example":{"job_id":"8a72d9f1-c4b5-4e6d-9b1f-0e3a2c6d8b04","object":"report.run","report_id":"8a72d9f1-c4b5-4e6d-9b1f-0e3a2c6d8b04","run_id":"8a72d9f1-c4b5-4e6d-9b1f-0e3a2c6d8b04"}},"ReportShare":{"properties":{"object":{"type":"string","const":"report.share","title":"Object","description":"Always `report.share`.","default":"report.share"},"id":{"type":"string","title":"Id","description":"Share id (UUID)."},"report_id":{"type":"string","title":"Report Id","description":"Owning report id (UUID)."},"brand_id":{"type":"string","title":"Brand Id","description":"Owning brand id (UUID)."},"share_type":{"type":"string","const":"report","title":"Share Type","description":"Always `report` (V1 only exposes single-report shares).","default":"report"},"access_token":{"type":"string","title":"Access Token","description":"URL-safe public token. Treat as secret; rotate via `POST` with `rotate=true`."},"share_url":{"type":"string","title":"Share Url","description":"Pre-rendered public URL to send to recipients."},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Expires At","description":"ISO-8601 timestamp after which the share returns `410 Gone`. `null` for the rare legacy rows created before the expiry window was mandatory; new shares always carry a value."},"is_existing":{"type":"boolean","title":"Is Existing","description":"`true` when the response refreshed an existing share rather than creating a new row.","default":false},"white_label_config":{"anyOf":[{"$ref":"#/components/schemas/ShareWhiteLabel"},{"type":"null"}],"description":"Account-level white-label branding applied to this share; null when the caller has none."},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Created At","description":"ISO-8601 timestamp the share row was first written."},"view_count":{"type":"integer","minimum":0.0,"title":"View Count","description":"Times this share has been viewed.","default":0},"last_viewed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Last Viewed At","description":"ISO-8601 timestamp the share was last viewed."},"has_password":{"type":"boolean","title":"Has Password","description":"Whether the share requires a password.","default":false}},"additionalProperties":false,"type":"object","required":["id","report_id","brand_id","access_token","share_url"],"title":"ReportShare","description":"A share link to a public, time-limited snapshot of a report.","example":{"access_token":"Hk2L8x9PqRsTuVwXyZ-aBcDeFgHiJkLmNoPqRsTuVwXyZ_AbCdE","brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","created_at":"2026-04-20T15:23:04.512+00:00","expires_at":"2026-05-20T15:23:04.512+00:00","id":"0d2c1b3a-4e5f-6789-abcd-ef0123456789","is_existing":false,"object":"report.share","report_id":"8a72d9f1-c4b5-4e6d-9b1f-0e3a2c6d8b04","share_type":"report","share_url":"https://app.rankprompt.com/shared/Hk2L8x9PqRsTuVwXyZ-aBcDeFgHiJkLmNoPqRsTuVwXyZ_AbCdE"}},"ReportShareCreate":{"properties":{"expiration_days":{"type":"integer","maximum":365.0,"minimum":1.0,"title":"Expiration Days","description":"Days until the share expires (1-365, default 30).","default":30},"rotate":{"type":"boolean","title":"Rotate","description":"When `true`, revoke every existing share the caller owns for this report and issue a fresh token. Default `false` keeps `POST` idempotent (refreshes the existing share's snapshot).","default":false},"password":{"anyOf":[{"type":"string","maxLength":128,"minLength":4},{"type":"null"}],"title":"Password","description":"Optional password to protect the share."}},"additionalProperties":false,"type":"object","title":"ReportShareCreate","description":"Body for ``POST /v1/reports/{report_id}/shares``.","example":{"expiration_days":30,"rotate":false}},"ReportShareList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/ReportShare"},"type":"array","title":"Data"}},"additionalProperties":false,"type":"object","required":["data"],"title":"ReportShareList","description":"The caller's non-expired shares for one report, newest first.","example":{"data":[{"access_token":"Hk2L8x9PqRsTuVwXyZ-aBcDeFgHiJkLmNoPqRsTuVwXyZ_AbCdE","brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","created_at":"2026-04-20T15:23:04.512+00:00","expires_at":"2026-05-20T15:23:04.512+00:00","id":"0d2c1b3a-4e5f-6789-abcd-ef0123456789","is_existing":false,"object":"report.share","report_id":"8a72d9f1-c4b5-4e6d-9b1f-0e3a2c6d8b04","share_type":"report","share_url":"https://app.rankprompt.com/shared/Hk2L8x9PqRsTuVwXyZ-aBcDeFgHiJkLmNoPqRsTuVwXyZ_AbCdE"}],"object":"list"}},"ReportShareUpdate":{"properties":{"expiration_days":{"type":"integer","maximum":365.0,"minimum":1.0,"title":"Expiration Days","description":"New expiry window from now (1-365 days). Replaces the current `expires_at`."}},"additionalProperties":false,"type":"object","required":["expiration_days"],"title":"ReportShareUpdate","description":"Body for ``PATCH /v1/reports/{report_id}/shares/{share_id}``.","example":{"expiration_days":60}},"ReportSummary":{"properties":{"object":{"type":"string","title":"Object","description":"Always `report_summary`.","default":"report_summary"},"report_id":{"type":"string","title":"Report Id","description":"The report this summary belongs to (UUID)."},"brand_id":{"type":"string","title":"Brand Id","description":"Owning brand id (UUID)."},"name":{"type":"string","title":"Name","description":"Human-readable report label."},"status":{"type":"string","enum":["draft","processing","completed","failed"],"title":"Status","description":"Report lifecycle status."},"visibility_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Visibility Score","description":"Aggregate brand visibility score (0-100). Null until the report completes."},"total_results":{"type":"integer","minimum":0.0,"title":"Total Results","description":"Total prompt-platform results materialised by the run.","default":0},"ranked_prompts":{"type":"integer","minimum":0.0,"title":"Ranked Prompts","description":"Prompt-platform results that surfaced the brand. Always <= `total_results`.","default":0},"degraded_cells_count":{"type":"integer","minimum":0.0,"title":"Degraded Cells Count","description":"Cells that returned degraded/partial data in this report.","default":0},"cells_permanently_failed":{"type":"integer","minimum":0.0,"title":"Cells Permanently Failed","description":"Cells that permanently failed after retries.","default":0},"ai_platforms":{"items":{"type":"string"},"type":"array","title":"Ai Platforms","description":"AI platforms the report ran against."},"ai_suggestion":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ai Suggestion","description":"Human-readable recommendation written by the LLM. `null` until the AI-suggestion step has been triggered for this report."},"ai_analysis":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Ai Analysis","description":"Structured companion to `ai_suggestion` (categories, trends, highlights, etc.)."},"generated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Generated At","description":"ISO-8601 timestamp the analysis was last refreshed. Falls back to the report's `created_at` while the analysis is `null`."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"ISO-8601 timestamp when the report was created."},"platform_breakdown":{"items":{"$ref":"#/components/schemas/VisibilitySlice"},"type":"array","title":"Platform Breakdown","description":"Visibility per AI engine, most appearances first. Where the brand wins and where it is absent."},"category_breakdown":{"items":{"$ref":"#/components/schemas/VisibilitySlice"},"type":"array","title":"Category Breakdown","description":"Visibility per prompt `category`, most appearances first. Segment by this before planning: a blended score hides a category the brand never appears in."},"visibility_band":{"anyOf":[{"$ref":"#/components/schemas/VisibilityBand"},{"type":"null"}],"description":"The score's 95% noise band and the change against the previous run, counted only over the answers both runs asked (`shared_answers`); new prompts are counted apart (`new_prompts`). Read a move inside the band as normal variation, not a trend. `null` until the report completes."}},"additionalProperties":false,"type":"object","required":["report_id","brand_id","name","status","created_at"],"title":"ReportSummary","description":"One-call digest of a report: headline metrics plus the LLM analysis.","example":{"ai_analysis":{"highlights":[{"category":"Trail Running","trend":"down"},{"category":"Running Shoes","trend":"up"}],"summary":"Brand visibility is improving on Running Shoes queries."},"ai_platforms":["chatgpt","claude","ai_overviews"],"ai_suggestion":"Visibility on ChatGPT improved by 12 points week-over-week, mostly driven by `Running Shoes` prompts. `Trail Running` still trails competitors. Consider publishing a head-to-head comparison page targeting that topic.","brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","cells_permanently_failed":0,"created_at":"2024-09-01T11:00:00+00:00","degraded_cells_count":0,"generated_at":"2024-09-01T11:42:11.117+00:00","name":"adidas weekly visibility, Sept 2024","object":"report_summary","ranked_prompts":17,"report_id":"8a72d9f1-c4b5-4e6d-9b1f-0e3a2c6d8b04","status":"completed","total_results":60,"visibility_band":{"answers":60,"delta":3.2,"high":49.6,"low":36.1,"movement":"steady","new_prompts":0,"previous_score":39.5,"runs":0,"shared_answers":60,"shared_score":42.7},"visibility_score":42.7}},"ReportUpdate":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Name"},"country":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Country"},"location":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Location","description":"Free-form location used to scope queries, e.g. `New York, NY` or `California`. More specific than `country`."},"language":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"title":"Language"},"ai_platforms":{"anyOf":[{"items":{"type":"string","enum":["chatgpt","claude","ai_overviews","grok","perplexity","gemini","muse"]},"type":"array","maxItems":10},{"type":"null"}],"title":"Ai Platforms","description":"AI platforms to query. Engines: `chatgpt`, `claude`, `ai_overviews`, `grok`, `perplexity`, `gemini`, `muse`. Each prompt costs 1 credit per 3 engines, rounded up: 1 to 3 engines cost 1 credit, 4 to 6 cost 2, all 7 cost 3. Any other value, retired ones included (`chatgpt_search`, `claude_search`), answers `ai_platform_unsupported`."}},"additionalProperties":false,"type":"object","title":"ReportUpdate","description":"Partial-update body for ``PATCH /v1/reports/{id}``."},"RequestQuota":{"properties":{"limit":{"type":"integer","minimum":0.0,"title":"Limit","description":"Total monthly request units included in the active SKU or plan."},"used":{"type":"integer","minimum":0.0,"title":"Used","description":"Request units consumed in the current billing period."},"remaining":{"type":"integer","minimum":0.0,"title":"Remaining","description":"Request units left before the next reset."}},"additionalProperties":false,"type":"object","required":["limit","used","remaining"],"title":"RequestQuota","description":"Per-period request counter (mirrors the ``X-RP-Quota-*`` headers).","example":{"limit":200000,"remaining":195769,"used":4231}},"ResearchItem":{"properties":{"search_volume":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Search Volume","description":"Average monthly Google searches."},"cpc":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cpc","description":"Average cost per click, in USD."},"competition":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Competition","description":"Paid competition from 0 to 1."},"competition_level":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Competition Level","description":"`LOW`, `MEDIUM` or `HIGH`."},"keyword_difficulty":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Keyword Difficulty","description":"How hard it is to rank organically, 0 to 100."},"main_intent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Main Intent","description":"Search intent: informational, navigational, commercial or transactional."},"trend":{"anyOf":[{"$ref":"#/components/schemas/KeywordTrend"},{"type":"null"}]},"monthly_searches":{"anyOf":[{"items":{"$ref":"#/components/schemas/MonthlySearches"},"type":"array"},{"type":"null"}],"title":"Monthly Searches","description":"The last months' volume."},"serp_item_types":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Serp Item Types","description":"What Google shows on the results page."},"has_ai_overview":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Ai Overview","description":"Google answers this keyword with an AI Overview. Null where the results page was not bought, which is the case on the keyword gap and on ranked keywords."},"fetched_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Fetched At","description":"When these numbers were bought."},"keyword":{"type":"string","title":"Keyword"},"tracked":{"type":"boolean","title":"Tracked"},"category_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category Label","description":"Google's most specific category for it."},"off_topic":{"anyOf":[{"type":"string","enum":["shopping","local"]},{"type":"null"}],"title":"Off Topic","description":"Why a result is not what the seed asked about: a shop or a place."}},"type":"object","required":["keyword","tracked"],"title":"ResearchItem"},"ResearchSeed":{"properties":{"search_volume":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Search Volume","description":"Average monthly Google searches."},"cpc":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cpc","description":"Average cost per click, in USD."},"competition":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Competition","description":"Paid competition from 0 to 1."},"competition_level":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Competition Level","description":"`LOW`, `MEDIUM` or `HIGH`."},"keyword_difficulty":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Keyword Difficulty","description":"How hard it is to rank organically, 0 to 100."},"main_intent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Main Intent","description":"Search intent: informational, navigational, commercial or transactional."},"trend":{"anyOf":[{"$ref":"#/components/schemas/KeywordTrend"},{"type":"null"}]},"monthly_searches":{"anyOf":[{"items":{"$ref":"#/components/schemas/MonthlySearches"},"type":"array"},{"type":"null"}],"title":"Monthly Searches","description":"The last months' volume."},"serp_item_types":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Serp Item Types","description":"What Google shows on the results page."},"has_ai_overview":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Ai Overview","description":"Google answers this keyword with an AI Overview. Null where the results page was not bought, which is the case on the keyword gap and on ranked keywords."},"fetched_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Fetched At","description":"When these numbers were bought."},"keyword":{"type":"string","title":"Keyword"},"category_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category Label"}},"type":"object","required":["keyword"],"title":"ResearchSeed"},"Review":{"properties":{"object":{"type":"string","const":"review","title":"Object","description":"Always `review`.","default":"review"},"review_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Review Id","description":"Review id, or null when the article has never been shared."},"status":{"type":"string","enum":["pending","approved","changes_requested"],"title":"Status","description":"Review state. `pending` when never shared."},"version":{"type":"integer","title":"Version","description":"Review round.","default":1},"is_shared":{"type":"boolean","title":"Is Shared","description":"False when the article has no share link yet."},"reviewer_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reviewer Name","description":"Name the client gave when responding."},"reviewer_email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reviewer Email","description":"Email the client gave when responding."},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Expires At","description":"When the link stops working."},"comments":{"items":{"$ref":"#/components/schemas/ReviewComment"},"type":"array","title":"Comments","description":"Comments, oldest first."}},"additionalProperties":false,"type":"object","required":["status","is_shared"],"title":"Review","description":"Agency-side view of a shared article: its state plus every comment on it."},"ReviewComment":{"properties":{"object":{"type":"string","const":"review_comment","title":"Object","description":"Always `review_comment`.","default":"review_comment"},"id":{"type":"string","title":"Id","description":"Comment id (UUID)."},"body":{"type":"string","title":"Body","description":"Comment text."},"author_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Author Name","description":"Display name of whoever left the comment."},"is_client":{"type":"boolean","title":"Is Client","description":"True when the comment came from the share link rather than the agency."},"resolved":{"type":"boolean","title":"Resolved","description":"Whether the comment has been marked resolved."},"parent_comment_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Comment Id","description":"Parent comment id when this is a reply, else null."},"anchor_quote":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Anchor Quote","description":"Quoted article text the comment is anchored to, when anchored."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the comment was left."}},"additionalProperties":false,"type":"object","required":["id","body","is_client","resolved","created_at"],"title":"ReviewComment","description":"A comment left on a shared article, by the client or by the agency."},"ReviewCommentCreate":{"properties":{"body":{"type":"string","maxLength":4000,"minLength":1,"title":"Body","description":"What the client reads."},"parent_comment_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Comment Id","description":"Reply to one of their comments."},"anchor_quote":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Anchor Quote","description":"The passage it is about, quoted from the article."},"anchor_start":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Anchor Start","description":"Character offset of that passage."}},"additionalProperties":false,"type":"object","required":["body"],"title":"ReviewCommentCreate","description":"Reply on the review thread the client sees."},"ReviewCommentUpdate":{"properties":{"resolved":{"type":"boolean","title":"Resolved","description":"`true` marks the comment resolved, `false` reopens it.","default":true}},"additionalProperties":false,"type":"object","title":"ReviewCommentUpdate","description":"Resolve or unresolve a comment."},"ReviewShare":{"properties":{"object":{"type":"string","const":"review_share","title":"Object","description":"Always `review_share`.","default":"review_share"},"review_id":{"type":"string","title":"Review Id","description":"Review id (UUID)."},"access_token":{"type":"string","title":"Access Token","description":"Capability token. Anyone holding it can read and comment."},"url":{"type":"string","title":"Url","description":"Ready-to-send link for the client. No login required."},"status":{"type":"string","enum":["pending","approved","changes_requested"],"title":"Status","description":"Review state. One of `pending`, `approved`, `changes_requested`."},"version":{"type":"integer","title":"Version","description":"Review round. Editing the article after feedback opens a new round."},"is_existing":{"type":"boolean","title":"Is Existing","description":"True when an existing share was refreshed instead of created."},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Expires At","description":"When the link stops working."}},"additionalProperties":false,"type":"object","required":["review_id","access_token","url","status","version","is_existing"],"title":"ReviewShare","description":"The share link that lets a client read the article and comment without an account."},"ReviewShareCreate":{"properties":{"expiration_days":{"type":"integer","maximum":365.0,"minimum":1.0,"title":"Expiration Days","description":"Days until the link stops working. Refreshing an existing share restarts this window.","default":30}},"additionalProperties":false,"type":"object","title":"ReviewShareCreate","description":"Options for creating or refreshing an article's review link."},"RunChange":{"properties":{"key":{"type":"string","title":"Key","description":"The run: its batch, else its report."},"changes":{"items":{"$ref":"#/components/schemas/RunPlaceChange"},"type":"array","title":"Changes","description":"The places whose ask changed."},"places_added":{"items":{"$ref":"#/components/schemas/RunPlace"},"type":"array","title":"Places Added","description":"Places this run added."},"places_removed":{"items":{"$ref":"#/components/schemas/RunPlace"},"type":"array","title":"Places Removed","description":"Places this run dropped."}},"additionalProperties":false,"type":"object","required":["key"],"title":"RunChange","description":"A run that asked other prompts, AI platforms or places than the run before it: a step, never a move."},"RunPlace":{"properties":{"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country"},"location":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language"},"region_config_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Region Config Id"}},"additionalProperties":false,"type":"object","title":"RunPlace","description":"Where a run asked: country, city and language, and the region config its report ran for."},"RunPlaceChange":{"properties":{"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country"},"location":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language"},"region_config_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Region Config Id"},"prompts_added":{"type":"integer","minimum":0.0,"title":"Prompts Added","description":"Prompts this run asked that the run before did not.","default":0},"prompts_removed":{"type":"integer","minimum":0.0,"title":"Prompts Removed","description":"Prompts the run before asked that this run did not.","default":0},"engines_added":{"items":{"type":"string"},"type":"array","title":"Engines Added","description":"AI platforms this run added."},"engines_removed":{"items":{"type":"string"},"type":"array","title":"Engines Removed","description":"AI platforms this run dropped."}},"additionalProperties":false,"type":"object","title":"RunPlaceChange","description":"What a run asked in one place that the run before it did not, and the reverse."},"SavedProspectSearch":{"properties":{"object":{"type":"string","const":"saved_prospect_search","title":"Object","default":"saved_prospect_search"},"id":{"type":"string","title":"Id"},"sector":{"type":"string","title":"Sector"},"location":{"type":"string","title":"Location"},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language"},"target_list_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target List Id"},"probe":{"type":"boolean","title":"Probe"},"is_active":{"type":"boolean","title":"Is Active"},"paused_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Paused Reason","description":"`credits`, `plan` or `user`."},"next_run_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Run At"},"last_run_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Run At"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"}},"additionalProperties":false,"type":"object","required":["id","sector","location","probe","is_active"],"title":"SavedProspectSearch","description":"A prospect search that runs again every week."},"SavedProspectSearchCreate":{"properties":{"sector":{"type":"string","maxLength":200,"minLength":1,"title":"Sector"},"location":{"type":"string","maxLength":200,"minLength":1,"title":"Location"},"country":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Country","description":"Full English name, e.g. `United States`."},"language":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Language"},"target_list_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target List Id","description":"Save each run's new businesses into this list."},"probe":{"type":"boolean","title":"Probe","description":"Ask the AI platforms who they name on each run; no extra credits.","default":true}},"additionalProperties":false,"type":"object","required":["sector","location"],"title":"SavedProspectSearchCreate","description":"A search to run every week, starting now.","example":{"country":"United States","location":"Austin, Texas","sector":"dental clinics"}},"SavedProspectSearchList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/SavedProspectSearch"},"type":"array","title":"Data"},"active_count":{"type":"integer","title":"Active Count"},"max_active":{"type":"integer","title":"Max Active"},"weekly_credits":{"type":"integer","title":"Weekly Credits"}},"additionalProperties":false,"type":"object","required":["data","active_count","max_active","weekly_credits"],"title":"SavedProspectSearchList","description":"The account's saved searches, with what the active ones spend every week."},"SavedProspectSearchRun":{"properties":{"object":{"type":"string","const":"saved_prospect_search_run","title":"Object","default":"saved_prospect_search_run"},"id":{"type":"string","title":"Id"},"ran_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ran At"},"found":{"type":"integer","title":"Found","default":0},"new_count":{"type":"integer","title":"New Count","description":"Businesses the account did not have yet.","default":0},"credits_charged":{"type":"integer","title":"Credits Charged","default":0},"status":{"type":"string","title":"Status","description":"`running`, `completed`, `failed` or `skipped`."},"error_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Code","description":"`no_credits`, `plan_required`, `paused`, `search_failed`."},"candidates":{"items":{"$ref":"#/components/schemas/ProspectCandidate"},"type":"array","title":"Candidates","description":"The new businesses of a run without a target list, to review."}},"additionalProperties":false,"type":"object","required":["id","status"],"title":"SavedProspectSearchRun","description":"One weekly run of a saved search."},"SavedProspectSearchRunList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/SavedProspectSearchRun"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"True when more items exist past this page. Fetch them with a larger `offset`."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of items matching the query, across all pages."},"limit":{"type":"integer","minimum":1.0,"title":"Limit","description":"Page size that was applied."},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of items skipped before this page."}},"additionalProperties":false,"type":"object","required":["data","has_more","total","limit","offset"],"title":"SavedProspectSearchRunList","description":"A page of a saved search's runs, newest first."},"SavedProspectSearchUpdate":{"properties":{"is_active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Active"},"target_list_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target List Id"},"probe":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Probe"}},"additionalProperties":false,"type":"object","title":"SavedProspectSearchUpdate","description":"Pause, resume or retarget a saved search."},"ScheduleAnalytics":{"properties":{"object":{"type":"string","title":"Object","default":"scheduled_report.analytics"},"scheduled_report_id":{"type":"string","title":"Scheduled Report Id"},"scheduled_report_name":{"type":"string","title":"Scheduled Report Name"},"total_runs":{"type":"integer","title":"Total Runs"},"avg_visibility":{"type":"number","title":"Avg Visibility","description":"Answers that named the brand over every answer of every prompt in every run, in percent."},"prompts":{"items":{"$ref":"#/components/schemas/ScheduleAnalyticsPromptTrend"},"type":"array","title":"Prompts"},"platform_performance":{"items":{"$ref":"#/components/schemas/SchedulePlatformPerformance"},"type":"array","title":"Platform Performance"},"regions":{"items":{"$ref":"#/components/schemas/ScheduleRegionSeries"},"type":"array","title":"Regions","description":"Per region config, its visibility in every completed run, to compare markets side by side."},"run_changes":{"items":{"$ref":"#/components/schemas/RunChange"},"type":"array","title":"Run Changes","description":"Runs that asked other prompts, AI platforms or places than the run before, keyed by run: a step there is not a gain or a loss."},"region_changes":{"items":{"$ref":"#/components/schemas/RegionChange"},"type":"array","title":"Region Changes","description":"Each region config's latest run against its run before, over the answers both asked."},"latest_change":{"anyOf":[{"$ref":"#/components/schemas/SharedChange"},{"type":"null"}],"description":"The latest run against the run before, pooled over its region configs; null with one run."}},"additionalProperties":false,"type":"object","required":["scheduled_report_id","scheduled_report_name","total_runs","avg_visibility"],"title":"ScheduleAnalytics","description":"``GET /v1/scheduled-reports/{id}/analytics`` response."},"ScheduleAnalyticsPromptTrend":{"properties":{"region_config_prompt_id":{"type":"string","title":"Region Config Prompt Id"},"region_config_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Region Config Id"},"current_prompt_text":{"type":"string","title":"Current Prompt Text"},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category"},"intent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Intent","description":"The prompt's funnel intent: `awareness` (learning about a topic), `consideration` (weighing options) or `decision` (choosing between named options); `null` when unclassified. Written with generated prompts, set by hand otherwise. An open set."},"run_count":{"type":"integer","title":"Run Count"},"avg_visibility_pct":{"type":"number","title":"Avg Visibility Pct","description":"The prompt's answers that named the brand over all its answers in every run, in percent."},"latest_visibility_pct":{"type":"number","title":"Latest Visibility Pct"},"latest_rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Latest Rank"},"trend_direction":{"type":"string","enum":["up","down","stable"],"title":"Trend Direction","description":"`up` or `down` when `trend_delta` moved more than 5 points either way, else `stable`."},"trend_delta":{"type":"number","title":"Trend Delta","description":"The newer half of the schedule's runs against the older half, in points: the runs ordered by start, the middle one of an odd count in neither half, each half's visibility its named answers over its answers. `0` under two runs or when the prompt has no answers in one half."},"sparkline_data":{"items":{"type":"number"},"type":"array","title":"Sparkline Data","description":"The prompt's visibility in each run, oldest first, in percent."}},"additionalProperties":false,"type":"object","required":["region_config_prompt_id","current_prompt_text","run_count","avg_visibility_pct","latest_visibility_pct","trend_direction","trend_delta","sparkline_data"],"title":"ScheduleAnalyticsPromptTrend","description":"Per-prompt trend row inside the analytics envelope."},"SchedulePlatformPerformance":{"properties":{"platform":{"type":"string","title":"Platform"},"total_runs":{"type":"integer","title":"Total Runs"},"appearances":{"type":"integer","title":"Appearances"},"appearance_rate":{"type":"number","title":"Appearance Rate"},"avg_rank":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Rank"},"best_rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Best Rank"}},"additionalProperties":false,"type":"object","required":["platform","total_runs","appearances","appearance_rate"],"title":"SchedulePlatformPerformance","description":"Per-platform performance row inside the analytics envelope."},"SchedulePromptHistory":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/SchedulePromptRun"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Opaque continuation token. Pass back as `?cursor=` to fetch the next page. `null` when `has_more` is false."},"scheduled_report_id":{"type":"string","title":"Scheduled Report Id"},"region_config_prompt_id":{"type":"string","title":"Region Config Prompt Id"},"prompt_text":{"type":"string","title":"Prompt Text"},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category"},"region_config_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Region Config Name"},"ai_platforms":{"items":{"type":"string"},"type":"array","title":"Ai Platforms","description":"The engines the market runs today, as `GET /v1/region-configs` returns them: a retired engine reads as the one that runs in its place."}},"additionalProperties":false,"type":"object","required":["data","has_more","scheduled_report_id","region_config_prompt_id","prompt_text"],"title":"SchedulePromptHistory","description":"One schedule prompt with a page of its runs, newest first."},"SchedulePromptRun":{"properties":{"report_id":{"type":"string","title":"Report Id"},"date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Date","description":"The run's slot: when its report was created."},"visibility_pct":{"type":"number","title":"Visibility Pct"},"total":{"type":"integer","title":"Total"},"ranked":{"type":"integer","title":"Ranked"},"platform_results":{"items":{"$ref":"#/components/schemas/SchedulePromptRunPlatform"},"type":"array","title":"Platform Results"}},"additionalProperties":false,"type":"object","required":["report_id","visibility_pct","total","ranked"],"title":"SchedulePromptRun","description":"A single execution slot in a prompt's run history."},"SchedulePromptRunPlatform":{"properties":{"ai_platform":{"type":"string","title":"Ai Platform"},"model_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model Version","description":"Model that produced this answer. Null only for answers predating tracking."},"brand_appears":{"type":"boolean","title":"Brand Appears"},"rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rank"},"response":{"type":"string","title":"Response","default":""},"citation_details":{"items":{"$ref":"#/components/schemas/ReportCitation"},"type":"array","title":"Citation Details","description":"The pages the answer cites, with the URL plus any title/snippet/source/favicon/thumbnail/grounding-span metadata the upstream provider returned. Same shape as the citations on report results; pages it only read are in `retrieved`."},"retrieved":{"items":{"$ref":"#/components/schemas/ReportCitation"},"type":"array","title":"Retrieved","description":"Pages the engine read while answering (search results, pages it opened) that its text does not cite; never in `citations`. Filled for ChatGPT, Claude, Gemini, Grok and Muse; empty for Perplexity and Google AI Mode, whose sources are all cited, and for answers recorded before it was kept. Claude, Gemini and Grok answers recorded before 2026-10-29 list these pages in `citations` too."},"fanouts":{"items":{"type":"string"},"type":"array","title":"Fanouts","description":"The web searches the engine ran to write this answer (fan-outs), in its order. Filled for ChatGPT, Claude, Gemini, Grok, Perplexity and Muse; empty for Google AI Mode, which does not report them."},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Created At","description":"When the engine was asked: later than the run's `date` when a failed run was retried."}},"additionalProperties":false,"type":"object","required":["ai_platform","brand_appears"],"title":"SchedulePromptRunPlatform","description":"One platform's slice of a single prompt-run."},"ScheduleRegionConfigCreate":{"properties":{"name":{"type":"string","maxLength":200,"minLength":1,"title":"Name","description":"Human-readable label."},"country":{"type":"string","maxLength":100,"minLength":1,"title":"Country","description":"Country the region targets."},"location":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Location","description":"Optional sub-region / city."},"language":{"type":"string","maxLength":50,"title":"Language","description":"Language. Accepts English name (`English`, `Spanish`) or ISO 639-1 code (`en`, `es`).","default":"English"},"ai_platforms":{"items":{"type":"string","enum":["chatgpt","claude","ai_overviews","grok","perplexity","gemini","muse"]},"type":"array","maxItems":10,"minItems":1,"title":"Ai Platforms","description":"AI platforms to run against (1-10), as on `POST /v1/region-configs`. Defaults to `[\"chatgpt\", \"claude\", \"ai_overviews\"]`."},"source_report_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Report Id","description":"Report of the same brand this config starts from, when applicable."},"is_active":{"type":"boolean","title":"Is Active","description":"Whether the config runs on scheduled executions. A config created without prompts starts paused.","default":true},"prompts":{"anyOf":[{"items":{"$ref":"#/components/schemas/RegionConfigPromptInput"},"type":"array","maxItems":50},{"type":"null"}],"title":"Prompts","description":"Up to 50 prompts to seed the config with."},"copy_report_prompts":{"type":"boolean","title":"Copy Report Prompts","description":"Seed the new config with the prompts of `source_report_id`, in the same call. A report with no prompts to copy leaves the config paused (`is_active: false`) instead of waking a schedule that would run nothing.","default":false}},"additionalProperties":false,"type":"object","required":["name","country"],"title":"ScheduleRegionConfigCreate","description":"One region config created together with its schedule in ``POST /v1/scheduled-reports``.","example":{"ai_platforms":["chatgpt","claude","ai_overviews"],"country":"Mexico","language":"Spanish","name":"Mexico, Spanish","prompts":[{"category":"Running shoes","prompt_text":"mejores tenis para correr"}]}},"ScheduleRegionConfigList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/RegionConfig"},"type":"array","title":"Data"}},"additionalProperties":false,"type":"object","required":["data"],"title":"ScheduleRegionConfigList","description":"Region configs attached to one schedule.","example":{"data":[{"ai_platforms":["chatgpt","claude","ai_overviews"],"brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","country":"United States","created_at":"2026-04-01T11:00:00+00:00","id":"018e7c2e-33ab-7df1-b1cd-2ac3a8f9112d","is_active":true,"language":"English","last_run_at":"2026-04-19T03:00:00+00:00","last_run_status":"completed","location":"New York, NY","name":"United States, English","object":"region_config","prompts_count":12,"scheduled_report_id":"018e7c2d-33ab-7df1-b1cd-2ac3a8f9112d","updated_at":"2026-04-19T03:00:00+00:00"}],"object":"list"}},"ScheduleRegionPoint":{"properties":{"report_id":{"type":"string","title":"Report Id","description":"The report the run left for this region config."},"batch_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Batch Id","description":"The run it belongs to; reports of one run share it."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the report was created."},"visibility":{"type":"number","title":"Visibility","description":"Percent of answers naming the brand, one decimal."}},"additionalProperties":false,"type":"object","required":["report_id","created_at","visibility"],"title":"ScheduleRegionPoint","description":"The visibility one region config reached in one completed run."},"ScheduleRegionSeries":{"properties":{"region_config_id":{"type":"string","title":"Region Config Id","description":"Join with `GET /v1/scheduled-reports/{id}/region-configs`."},"points":{"items":{"$ref":"#/components/schemas/ScheduleRegionPoint"},"type":"array","title":"Points"},"platform_performance":{"items":{"$ref":"#/components/schemas/SchedulePlatformPerformance"},"type":"array","title":"Platform Performance","description":"Appearance rate and ranks per AI platform over this region config's prompts, the same window and shape as the top-level `platform_performance`: the Overview's location filter."}},"additionalProperties":false,"type":"object","required":["region_config_id"],"title":"ScheduleRegionSeries","description":"One region config's visibility per completed run, oldest first, and its platform performance."},"ScheduleRun":{"properties":{"object":{"type":"string","const":"scheduled_report.run","title":"Object","description":"Always `scheduled_report.run`.","default":"scheduled_report.run"},"key":{"type":"string","title":"Key","description":"Stable id of the run."},"batch_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Batch Id","description":"The run's id, the `batch_id` its reports share."},"started_at":{"type":"string","format":"date-time","title":"Started At","description":"When the run started."},"status":{"anyOf":[{"type":"string","enum":["processing","completed","failed"]},{"type":"null"}],"title":"Status","description":"`processing` while it runs, `completed` when at least one region config completed, else `failed`."},"reports":{"items":{"$ref":"#/components/schemas/ScheduleRunReport"},"type":"array","title":"Reports","description":"One report per region config, sorted by name."}},"additionalProperties":false,"type":"object","required":["key","started_at","reports"],"title":"ScheduleRun","description":"One run of a schedule: the report it left for each region config."},"ScheduleRunList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/ScheduleRun"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"True when more items exist past this page. Fetch them with a larger `offset`."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of items matching the query, across all pages."},"limit":{"type":"integer","minimum":1.0,"title":"Limit","description":"Page size that was applied."},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of items skipped before this page."}},"additionalProperties":false,"type":"object","required":["data","has_more","total","limit","offset"],"title":"ScheduleRunList","description":"A page of a schedule's runs, newest first."},"ScheduleRunReport":{"properties":{"report_id":{"type":"string","title":"Report Id","description":"Read it with `GET /v1/reports/{report_id}`."},"name":{"type":"string","title":"Name","description":"Report name."},"status":{"type":"string","enum":["draft","processing","completed","failed"],"title":"Status","description":"Report lifecycle status."},"visibility_score":{"type":"number","title":"Visibility Score","description":"Percent of answers naming the brand."},"ranked_prompts_count":{"type":"integer","minimum":0.0,"title":"Ranked Prompts Count","description":"Prompts where the brand appeared."},"total_prompts_count":{"type":"integer","minimum":0.0,"title":"Total Prompts Count","description":"Prompts the report ran."},"region_config_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Region Config Id","description":"The region config it ran for."},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country","description":"Country of that region config at run time."},"location":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location","description":"City or sub-region, when set."},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language","description":"Language of the run."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the report was created."}},"additionalProperties":false,"type":"object","required":["report_id","name","status","visibility_score","ranked_prompts_count","total_prompts_count","created_at"],"title":"ScheduleRunReport","description":"The report a run left for one region config."},"ScheduleSlot":{"properties":{"tz":{"type":"string","maxLength":64,"minLength":1,"title":"Tz","description":"IANA time zone, e.g. America/New_York."},"time":{"type":"string","title":"Time","description":"HH:MM on a 24-hour clock, local to tz."},"dow":{"anyOf":[{"type":"integer","maximum":6.0,"minimum":0.0},{"type":"null"}],"title":"Dow","description":"Weekly: 0 = Sunday."},"dom":{"anyOf":[{"type":"integer","maximum":28.0,"minimum":1.0},{"type":"null"}],"title":"Dom","description":"Monthly: day of the month, 1 to 28."}},"additionalProperties":false,"type":"object","required":["tz","time"],"title":"ScheduleSlot","description":"When the schedule runs: a local time in an IANA time zone, every day, on a weekday or on a day of the month.","example":{"dow":1,"time":"09:00","tz":"America/New_York"}},"ScheduledReport":{"properties":{"object":{"type":"string","title":"Object","description":"Always `scheduled_report`.","default":"scheduled_report"},"id":{"type":"string","title":"Id","description":"Stable schedule identifier (UUID)."},"brand_id":{"type":"string","title":"Brand Id","description":"Owning brand id (UUID)."},"name":{"type":"string","title":"Name","description":"Human-readable label."},"frequency":{"type":"string","enum":["daily","weekly","monthly"],"title":"Frequency","description":"Cadence the schedule runs at."},"is_active":{"type":"boolean","title":"Is Active","description":"Whether the schedule will run on its next tick."},"next_run_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Next Run At","description":"ISO-8601 timestamp of the next scheduled execution."},"last_run_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Last Run At","description":"ISO-8601 timestamp of the last execution."},"last_run_status":{"anyOf":[{"type":"string","enum":["processing","completed","failed"]},{"type":"null"}],"title":"Last Run Status","description":"Outcome of the last execution."},"last_error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Error Message","description":"Human-readable failure reason from the last run, when applicable."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"ISO-8601 timestamp when the schedule was created."},"deliver_to_client":{"type":"boolean","title":"Deliver To Client","description":"Email a branded report to the client after every completed run: a PDF built from the schedule's template, sent from the agency's sending domain to `recipient_emails` plus the brand's client email. Needs the brand owner on Agency; asking for it below that answers `403 brand_plan_required`. A trial sends up to 20 client report emails in all; the recipients past them wait for the subscription.","default":false},"recipient_emails":{"items":{"type":"string"},"type":"array","title":"Recipient Emails","description":"Extra recipients of the client report (up to 10), on top of the brand's client email."},"cc_self":{"type":"boolean","title":"Cc Self","description":"Copy the schedule owner on every client report.","default":false},"client_intro_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Client Intro Message","description":"A short note that opens the client report email."},"template_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Template Key","description":"House report template the run is composed from. Pass an empty string to clear it and fall back to the account's default template."},"account_template_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Account Template Id","description":"One of the account's own report templates, used instead of a house template. Pass an empty string to clear it."},"require_review":{"type":"boolean","title":"Require Review","description":"When `true` (the default for new schedules) the composed report waits for someone to approve and send it in the app. Set `false` to have it sent automatically when the run completes.","default":true},"last_delivered_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Last Delivered At","description":"When the last client report was sent or attempted."},"last_delivery_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Delivery Status","description":"Outcome of the last client delivery, e.g. `sent 2/3` or `skipped: no recipients`."},"status":{"anyOf":[{"type":"string","enum":["active","paused","archived"]},{"type":"null"}],"title":"Status","description":"`active`, `paused` or `archived`; `is_active` is `status == active`."},"paused_reason":{"anyOf":[{"type":"string","enum":["user","credits","no_markets","no_prompts"]},{"type":"null"}],"title":"Paused Reason","description":"Why a paused schedule is paused: `user`, `credits` (the account ran out), `no_markets` (it waits for its first region config) or `no_prompts` (also a schedule waiting for a region config's city, with the reason in `last_error_message`)."},"schedule":{"anyOf":[{"$ref":"#/components/schemas/ScheduleSlot"},{"type":"null"}],"description":"The slot `next_run_at` follows: a local time in a time zone, with the weekday or day of month."}},"additionalProperties":false,"type":"object","required":["id","brand_id","name","frequency","is_active","created_at"],"title":"ScheduledReport","description":"A scheduled report.","example":{"brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","cc_self":false,"created_at":"2026-03-01T10:00:00+00:00","deliver_to_client":true,"frequency":"weekly","id":"018e7c2d-33ab-7df1-b1cd-2ac3a8f9112d","is_active":true,"last_delivered_at":"2026-04-01T09:04:40+00:00","last_delivery_status":"sent 1/1","last_run_at":"2026-04-01T09:00:11.412+00:00","last_run_status":"completed","name":"adidas weekly visibility","next_run_at":"2026-04-08T09:00:00+00:00","object":"scheduled_report","recipient_emails":["marketing@e2e.test"],"require_review":false,"schedule":{"dow":3,"time":"09:00","tz":"America/New_York"},"status":"active"}},"ScheduledReportCreate":{"properties":{"brand_id":{"type":"string","title":"Brand Id","description":"Brand to attach the schedule to (UUID)."},"name":{"type":"string","maxLength":200,"minLength":1,"title":"Name","description":"Human-readable label that surfaces in dashboards/emails."},"frequency":{"type":"string","enum":["daily","weekly","monthly"],"title":"Frequency","description":"How often the schedule runs (`daily`, `weekly`, `monthly`)."},"deliver_to_client":{"type":"boolean","title":"Deliver To Client","description":"Email a branded report to the client after every completed run: a PDF built from the schedule's template, sent from the agency's sending domain to `recipient_emails` plus the brand's client email. Needs the brand owner on Agency; asking for it below that answers `403 brand_plan_required`. A trial sends up to 20 client report emails in all; the recipients past them wait for the subscription.","default":false},"recipient_emails":{"items":{"type":"string"},"type":"array","maxItems":10,"title":"Recipient Emails","description":"Extra recipients of the client report (up to 10), on top of the brand's client email."},"cc_self":{"type":"boolean","title":"Cc Self","description":"Copy the schedule owner on every client report.","default":false},"client_intro_message":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Client Intro Message","description":"A short note that opens the client report email."},"template_key":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Template Key","description":"House report template the run is composed from. Pass an empty string to clear it and fall back to the account's default template."},"account_template_id":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Account Template Id","description":"One of the account's own report templates, used instead of a house template. Pass an empty string to clear it."},"require_review":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Require Review","description":"When `true` (the default for new schedules) the composed report waits for someone to approve and send it in the app. Set `false` to have it sent automatically when the run completes."},"schedule":{"anyOf":[{"$ref":"#/components/schemas/ScheduleSlot"},{"type":"null"}],"description":"When the runs happen: `time` (HH:MM) in `tz`, plus `dow` (0 = Sunday) for weekly and `dom` (1 to 28) for monthly. Without it the schedule runs at the time of day it was created, in UTC, one period from now."},"region_configs":{"items":{"$ref":"#/components/schemas/ScheduleRegionConfigCreate"},"type":"array","maxItems":20,"title":"Region Configs","description":"Region configs to create with the schedule, up to 20: one per market (country, optional city, language), each seeded with its own `prompts` or with the prompts of its `source_report_id` (`copy_report_prompts`). Every run leaves one report per active config, never a merged one. All or nothing: if one config fails, the schedule is not created."}},"additionalProperties":false,"type":"object","required":["brand_id","name","frequency"],"title":"ScheduledReportCreate","description":"Request body for ``POST /v1/scheduled-reports``.","example":{"brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","frequency":"weekly","name":"adidas weekly visibility"}},"ScheduledReportDuplicate":{"properties":{"name":{"type":"string","maxLength":200,"minLength":1,"title":"Name","description":"Name of the new schedule."},"frequency":{"type":"string","enum":["daily","weekly","monthly"],"title":"Frequency","description":"Cadence of the new schedule."},"schedule":{"anyOf":[{"$ref":"#/components/schemas/ScheduleSlot"},{"type":"null"}],"description":"The copy's slot; without it the copy runs at the time of day it was made, in UTC."},"target_brand_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Brand Id","description":"Copy it into this brand instead (you need editor access there): the source brand's name in the prompts becomes the target's, a market on one of the source's places becomes a city market, and client delivery is not copied."}},"additionalProperties":false,"type":"object","required":["name","frequency"],"title":"ScheduledReportDuplicate","description":"Body for ``POST /v1/scheduled-reports/{id}/duplicates``.","example":{"frequency":"weekly","name":"Nike weekly visibility (copy)"}},"ScheduledReportList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/ScheduledReport"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Opaque continuation token. Pass back as `?cursor=` to fetch the next page. `null` when `has_more` is false."}},"additionalProperties":false,"type":"object","required":["data","has_more"],"title":"ScheduledReportList","description":"Cursor-paginated list of scheduled reports.","example":{"data":[{"brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","cc_self":false,"created_at":"2026-03-01T10:00:00+00:00","deliver_to_client":true,"frequency":"weekly","id":"018e7c2d-33ab-7df1-b1cd-2ac3a8f9112d","is_active":true,"last_delivered_at":"2026-04-01T09:04:40+00:00","last_delivery_status":"sent 1/1","last_run_at":"2026-04-01T09:00:11.412+00:00","last_run_status":"completed","name":"adidas weekly visibility","next_run_at":"2026-04-08T09:00:00+00:00","object":"scheduled_report","recipient_emails":["marketing@e2e.test"],"require_review":false,"schedule":{"dow":3,"time":"09:00","tz":"America/New_York"},"status":"active"}],"has_more":false,"object":"list"}},"ScheduledReportRun":{"properties":{"region_config_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Region Config Id","description":"Optional: run only this region config (must belong to the schedule)."}},"additionalProperties":false,"type":"object","title":"ScheduledReportRun","description":"Body for ``POST /v1/scheduled-reports/{id}/executions``."},"ScheduledReportRunDispatched":{"properties":{"object":{"type":"string","title":"Object","description":"Always `scheduled_report.execution`.","default":"scheduled_report.execution"},"scheduled_report_id":{"type":"string","title":"Scheduled Report Id"},"job_id":{"type":"string","title":"Job Id","description":"Poll `GET /v1/jobs/{job_id}` for progress."},"run_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run Id","description":"The run started: the `batch_id` of its reports and the `scheduled_run_id` of its webhooks."},"report_ids":{"items":{"type":"string"},"type":"array","title":"Report Ids","description":"The report the run builds for each region config, readable at once."}},"additionalProperties":false,"type":"object","required":["scheduled_report_id","job_id"],"title":"ScheduledReportRunDispatched","description":"202 envelope for a dispatched manual schedule run."},"ScheduledReportShare":{"properties":{"object":{"type":"string","const":"scheduled_report.share","title":"Object","description":"Always `scheduled_report.share`.","default":"scheduled_report.share"},"id":{"type":"string","title":"Id","description":"Share id (UUID)."},"scheduled_report_id":{"type":"string","title":"Scheduled Report Id","description":"Owning scheduled-report id (UUID)."},"brand_id":{"type":"string","title":"Brand Id","description":"Owning brand id (UUID)."},"share_type":{"type":"string","const":"scheduled","title":"Share Type","description":"Always `scheduled`.","default":"scheduled"},"access_token":{"type":"string","title":"Access Token","description":"URL-safe public token. Treat as secret; rotate via `POST` with `rotate=true`."},"share_url":{"type":"string","title":"Share Url","description":"Pre-rendered public URL to send to recipients."},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Expires At","description":"ISO-8601 timestamp after which the share returns `410 Gone`."},"is_existing":{"type":"boolean","title":"Is Existing","description":"`true` when the response refreshed an existing share rather than creating a new row.","default":false},"white_label_config":{"anyOf":[{"$ref":"#/components/schemas/ShareWhiteLabel"},{"type":"null"}],"description":"Account-level white-label branding applied to this share; null when the caller has none."},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Created At","description":"ISO-8601 timestamp the share row was first written."},"view_count":{"type":"integer","minimum":0.0,"title":"View Count","description":"Times this share has been viewed.","default":0},"last_viewed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Last Viewed At","description":"ISO-8601 timestamp the share was last viewed."},"refresh_on_view":{"type":"boolean","title":"Refresh On View","description":"Whether the link always shows the latest run: it rebuilds after each run and when its data changes, at most once every 5 minutes.","default":false},"has_password":{"type":"boolean","title":"Has Password","description":"Whether the share requires a password.","default":false}},"additionalProperties":false,"type":"object","required":["id","scheduled_report_id","brand_id","access_token","share_url"],"title":"ScheduledReportShare","description":"A share link to a public, time-limited snapshot of a scheduled report.","example":{"access_token":"Hk2L8x9PqRsTuVwXyZ-aBcDeFgHiJkLmNoPqRsTuVwXyZ_AbCdE","brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","created_at":"2026-04-20T15:23:04.512+00:00","expires_at":"2026-05-20T15:23:04.512+00:00","id":"0d2c1b3a-4e5f-6789-abcd-ef0123456789","is_existing":false,"object":"scheduled_report.share","scheduled_report_id":"8a72d9f1-c4b5-4e6d-9b1f-0e3a2c6d8b04","share_type":"scheduled","share_url":"https://app.rankprompt.com/shared/Hk2L8x9PqRsTuVwXyZ-aBcDeFgHiJkLmNoPqRsTuVwXyZ_AbCdE"}},"ScheduledReportShareCreate":{"properties":{"expiration_days":{"type":"integer","maximum":365.0,"minimum":1.0,"title":"Expiration Days","description":"Days until the share expires (1-365, default 30).","default":30},"rotate":{"type":"boolean","title":"Rotate","description":"When `true`, revoke every existing share the caller owns for this scheduled report and issue a fresh token. Default `false` keeps `POST` idempotent (refreshes the existing share's snapshot).","default":false},"refresh_on_view":{"type":"boolean","title":"Refresh On View","description":"Whether the link always shows the latest run: it rebuilds after each run and when its data changes, at most once every 5 minutes.","default":false},"password":{"anyOf":[{"type":"string","maxLength":128,"minLength":4},{"type":"null"}],"title":"Password","description":"Optional password to protect the share."}},"additionalProperties":false,"type":"object","title":"ScheduledReportShareCreate","description":"Body for ``POST /v1/scheduled-reports/{scheduled_report_id}/shares``.","example":{"expiration_days":30,"rotate":false}},"ScheduledReportShareList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/ScheduledReportShare"},"type":"array","title":"Data"}},"additionalProperties":false,"type":"object","required":["data"],"title":"ScheduledReportShareList","description":"The caller's non-expired shares for one scheduled report, newest first.","example":{"data":[{"access_token":"Hk2L8x9PqRsTuVwXyZ-aBcDeFgHiJkLmNoPqRsTuVwXyZ_AbCdE","brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","created_at":"2026-04-20T15:23:04.512+00:00","expires_at":"2026-05-20T15:23:04.512+00:00","id":"0d2c1b3a-4e5f-6789-abcd-ef0123456789","is_existing":false,"object":"scheduled_report.share","scheduled_report_id":"8a72d9f1-c4b5-4e6d-9b1f-0e3a2c6d8b04","share_type":"scheduled","share_url":"https://app.rankprompt.com/shared/Hk2L8x9PqRsTuVwXyZ-aBcDeFgHiJkLmNoPqRsTuVwXyZ_AbCdE"}],"object":"list"}},"ScheduledReportShareUpdate":{"properties":{"expiration_days":{"type":"integer","maximum":365.0,"minimum":1.0,"title":"Expiration Days","description":"New expiry window from now (1-365 days). Replaces the current `expires_at`."}},"additionalProperties":false,"type":"object","required":["expiration_days"],"title":"ScheduledReportShareUpdate","description":"Body for ``PATCH /v1/scheduled-reports/{scheduled_report_id}/shares/{share_id}``.","example":{"expiration_days":60}},"ScheduledReportUpdate":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":200,"minLength":1},{"type":"null"}],"title":"Name"},"frequency":{"anyOf":[{"type":"string","enum":["daily","weekly","monthly"]},{"type":"null"}],"title":"Frequency","description":"New cadence. `next_run_at` is recomputed from the schedule's slot (its time of day, and the weekday or day of month of the current next run when the slot has none); pass `next_run_at` or `schedule` to choose."},"is_active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Active","description":"Set to `false` to pause; `true` to resume."},"next_run_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Run At","description":"Override the next execution time (ISO-8601 UTC, include `Z` or offset). The schedule's slot moves to its time of day (and weekday or day of month) in the slot's time zone, so later runs follow it."},"schedule":{"anyOf":[{"$ref":"#/components/schemas/ScheduleSlot"},{"type":"null"}],"description":"A new slot; `next_run_at` becomes its next occurrence unless you pass one."},"deliver_to_client":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Deliver To Client","description":"Email a branded report to the client after every completed run: a PDF built from the schedule's template, sent from the agency's sending domain to `recipient_emails` plus the brand's client email. Needs the brand owner on Agency; asking for it below that answers `403 brand_plan_required`. A trial sends up to 20 client report emails in all; the recipients past them wait for the subscription."},"recipient_emails":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":10},{"type":"null"}],"title":"Recipient Emails","description":"Extra recipients of the client report (up to 10), on top of the brand's client email."},"cc_self":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Cc Self","description":"Copy the schedule owner on every client report."},"client_intro_message":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Client Intro Message","description":"A short note that opens the client report email."},"template_key":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Template Key","description":"House report template the run is composed from. Pass an empty string to clear it and fall back to the account's default template."},"account_template_id":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Account Template Id","description":"One of the account's own report templates, used instead of a house template. Pass an empty string to clear it."},"require_review":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Require Review","description":"When `true` (the default for new schedules) the composed report waits for someone to approve and send it in the app. Set `false` to have it sent automatically when the run completes."}},"additionalProperties":false,"type":"object","title":"ScheduledReportUpdate","description":"Partial-update body for ``PATCH /v1/scheduled-reports/{id}``.","example":{"is_active":false,"name":"adidas weekly visibility (renamed)"}},"SearchPerformance":{"properties":{"object":{"type":"string","const":"search_performance","title":"Object","default":"search_performance"},"engine":{"type":"string","enum":["google","bing"],"title":"Engine","description":"`google` (Search Console) or `bing` (Bing Webmaster Tools), as asked.","default":"google"},"dimension":{"type":"string","enum":["query","page","country","device","date"],"title":"Dimension","description":"What each row stands for."},"query":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Query","description":"Set when the rows are one query's history by date."},"data":{"items":{"$ref":"#/components/schemas/SearchRow"},"type":"array","title":"Data","description":"Rows for the dimension, most clicks first (by day for `date`). `query` is every query Search Console exposes for the window, a page at a time; the other dimensions come whole from the stored snapshot: the top 1000 pages, 300 countries, every device, one row per day."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Rows the dimension holds for the window, across every page."},"has_more":{"type":"boolean","title":"Has More","description":"With `dimension=query`, true when more queries follow: raise `offset`.","default":false},"totals":{"anyOf":[{"$ref":"#/components/schemas/SearchRow"},{"type":"null"}],"description":"Totals for the window. `key` is `site` when they come from a site-wide query, and `sum_of_rows` when only the rows were stored. With `query` they stay the site's, not that query's."},"site_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Site Url","description":"The connected Search Console site, or the Bing Webmaster Tools site with `bing`."},"date_range_start":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Date Range Start"},"date_range_end":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Date Range End"},"data_through":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Data Through","description":"Last day Search Console has complete data for; it lags two to three days."},"last_sync_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Last Sync At","description":"When Google was last read for this window; null when nothing is stored for it. Refresh when it is null or old."}},"additionalProperties":false,"type":"object","required":["dimension","data","total"],"title":"SearchPerformance","description":"Search Console performance for one dimension, with the site-wide totals of the same window."},"SearchRow":{"properties":{"object":{"type":"string","const":"search_row","title":"Object","default":"search_row"},"key":{"type":"string","title":"Key","description":"The dimension value: the query, page URL, country, device or date."},"clicks":{"type":"integer","minimum":0.0,"title":"Clicks","default":0},"impressions":{"type":"integer","minimum":0.0,"title":"Impressions","default":0},"ctr":{"type":"number","title":"Ctr","description":"Clicks over impressions, as a percentage.","default":0.0},"position":{"type":"number","title":"Position","description":"Average position in the engine's results, lower is better; 0 when Bing sent none.","default":0.0}},"additionalProperties":false,"type":"object","required":["key"],"title":"SearchRow","description":"One Search Console row: the dimension value and what it earned in the window."},"SegmentCondition":{"properties":{"field":{"type":"string","maxLength":100,"title":"Field","description":"The contact field, e.g. `tier`, `tags`, `email_verified`."},"operator":{"type":"string","maxLength":50,"title":"Operator","description":"The operator the field takes, e.g. `equals`, `contains`, `gte`."},"value":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"items":{},"type":"array"},{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Value","description":"The value to compare."}},"additionalProperties":false,"type":"object","required":["field","operator"],"title":"SegmentCondition","description":"One condition of a dynamic list's filter."},"SegmentFilter":{"properties":{"operator":{"type":"string","enum":["AND","OR"],"title":"Operator","description":"How the conditions combine.","default":"AND"},"conditions":{"items":{"$ref":"#/components/schemas/SegmentCondition"},"type":"array","maxItems":50,"title":"Conditions","description":"The conditions."}},"additionalProperties":false,"type":"object","title":"SegmentFilter","description":"A dynamic list's filter: conditions joined by one operator."},"SeoAudit":{"properties":{"object":{"type":"string","const":"seo_audit","title":"Object","description":"Always `seo_audit`.","default":"seo_audit"},"id":{"type":"string","title":"Id","description":"Audit id (UUID)."},"page_id":{"type":"string","title":"Page Id","description":"Page this audit belongs to (UUID)."},"brand_id":{"type":"string","title":"Brand Id","description":"Owning brand id (UUID)."},"status":{"type":"string","enum":["processing","completed","failed"],"title":"Status","description":"Audit lifecycle state. One of `processing`, `completed`, `failed`."},"scores":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Scores","description":"Lighthouse category scores (performance, accessibility, best_practices, seo), 0-100."},"core_web_vitals":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Core Web Vitals","description":"Lab metrics measured during the audit: `lcp_ms`, `cls`, `fcp_ms`, `tbt_ms` (Total Blocking Time; a lab run has no interactions, so real INP is only in `field_data`) and `ttfb_ms`."},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message","description":"User-facing failure reason when `status` is `failed`."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the audit was requested."},"started_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Started At","description":"When the audit began running."},"finished_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Finished At","description":"When the audit finished (completed or failed)."},"issues":{"items":{},"type":"array","title":"Issues","description":"Detailed issues found by the audit, each with a category, title, and impact; a performance opportunity also carries what fixing it would save as Lighthouse estimates it (`savings_ms`, `savings_bytes`)."},"field_data":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Field Data","description":"Real-user Core Web Vitals (p75) from Chrome users, when the page has enough traffic."}},"additionalProperties":false,"type":"object","required":["id","page_id","brand_id","status","created_at"],"title":"SeoAudit","description":"A complete Lighthouse audit, including the detailed per-check issues and real-user field data."},"SeoAuditList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/SeoAuditSummary"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Opaque continuation token. Pass back as `?cursor=` to fetch the next page. `null` when `has_more` is false."}},"additionalProperties":false,"type":"object","required":["data","has_more"],"title":"SeoAuditList","description":"A cursor-paginated page of audits for one tracked page."},"SeoAuditSummary":{"properties":{"object":{"type":"string","const":"seo_audit","title":"Object","description":"Always `seo_audit`.","default":"seo_audit"},"id":{"type":"string","title":"Id","description":"Audit id (UUID)."},"page_id":{"type":"string","title":"Page Id","description":"Page this audit belongs to (UUID)."},"brand_id":{"type":"string","title":"Brand Id","description":"Owning brand id (UUID)."},"status":{"type":"string","enum":["processing","completed","failed"],"title":"Status","description":"Audit lifecycle state. One of `processing`, `completed`, `failed`."},"scores":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Scores","description":"Lighthouse category scores (performance, accessibility, best_practices, seo), 0-100."},"core_web_vitals":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Core Web Vitals","description":"Lab metrics measured during the audit: `lcp_ms`, `cls`, `fcp_ms`, `tbt_ms` (Total Blocking Time; a lab run has no interactions, so real INP is only in `field_data`) and `ttfb_ms`."},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message","description":"User-facing failure reason when `status` is `failed`."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the audit was requested."},"started_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Started At","description":"When the audit began running."},"finished_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Finished At","description":"When the audit finished (completed or failed)."}},"additionalProperties":false,"type":"object","required":["id","page_id","brand_id","status","created_at"],"title":"SeoAuditSummary","description":"A Lighthouse audit as it appears in a list, with the detailed per-check issues and real-user field data omitted."},"SeoCruxHistory":{"properties":{"object":{"type":"string","const":"seo_crux_history","title":"Object","description":"Always `seo_crux_history`.","default":"seo_crux_history"},"available":{"type":"boolean","title":"Available","description":"True when a real-user trend is available for this page."},"page_url":{"type":"string","title":"Page Url","description":"URL the trend was fetched for."},"history":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"History","description":"Weekly p75 series per metric, when available; `null` when there is not enough real-user data."}},"additionalProperties":false,"type":"object","required":["available","page_url"],"title":"SeoCruxHistory","description":"Core Web Vitals weekly trend (75th percentile) for a page, sourced from real Chrome users."},"SeoOverview":{"properties":{"object":{"type":"string","const":"seo_overview","title":"Object","default":"seo_overview"},"target":{"$ref":"#/components/schemas/KeywordTarget"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"},"tracked":{"$ref":"#/components/schemas/KeywordSummary"},"brand":{"anyOf":[{"$ref":"#/components/schemas/DomainEntry"},{"type":"null"}]},"competitors":{"items":{"$ref":"#/components/schemas/DomainEntry"},"type":"array","title":"Competitors"},"competitors_total":{"type":"integer","title":"Competitors Total","description":"Competitors with a site, before `competitors_limit` trims the two lists.","default":0},"available_competitors":{"items":{"$ref":"#/components/schemas/AvailableCompetitor"},"type":"array","title":"Available Competitors","description":"Every competitor with a site, most mentioned first, with whether its data is cached or stale."},"ranked_keywords":{"items":{"$ref":"#/components/schemas/RankedKeyword"},"type":"array","title":"Ranked Keywords"},"ranked_keywords_total":{"type":"integer","title":"Ranked Keywords Total","description":"Ranked keywords before `limit` and `offset`.","default":0},"cache":{"$ref":"#/components/schemas/CacheState","description":"Whether a paid refresh has anything to buy."},"credits_charged":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Credits Charged","description":"Only on a refresh."}},"type":"object","required":["target","tracked","competitors","available_competitors","ranked_keywords","cache"],"title":"SeoOverview","description":"How the brand's domain and its competitors' rank in Google, and the keywords the domain ranks for."},"SeoPage":{"properties":{"object":{"type":"string","const":"seo_page","title":"Object","description":"Always `seo_page`.","default":"seo_page"},"id":{"type":"string","title":"Id","description":"Page id (UUID)."},"brand_id":{"type":"string","title":"Brand Id","description":"Owning brand id (UUID)."},"url":{"type":"string","title":"Url","description":"Page URL being tracked."},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Label","description":"Optional human-friendly label for the page."},"device":{"type":"string","enum":["mobile","desktop"],"title":"Device","description":"Device profile audits run under. One of `mobile`, `desktop`."},"is_auditing":{"type":"boolean","title":"Is Auditing","description":"True when an audit is currently running for this page.","default":false},"last_audit":{"anyOf":[{"$ref":"#/components/schemas/SeoAuditSummary"},{"type":"null"}],"description":"The most recent completed audit for this page, when one exists."},"previous_audit":{"anyOf":[{"$ref":"#/components/schemas/SeoAuditSummary"},{"type":"null"}],"description":"The second-most-recent completed audit for this page, for comparison against `last_audit`."},"technical":{"anyOf":[{"$ref":"#/components/schemas/SeoTechnicalSummary"},{"type":"null"}],"description":"The latest completed technical check (indexability, AI crawlers robots.txt blocks, structured data); null when none has run. Listing and reading a page carry it; creating or updating one does not."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the page was added."},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Updated At","description":"When the page was last updated."}},"additionalProperties":false,"type":"object","required":["id","brand_id","url","device","created_at"],"title":"SeoPage","description":"A page you track for Lighthouse audits and technical SEO checks."},"SeoPageCandidate":{"properties":{"object":{"type":"string","const":"seo_page_candidate","title":"Object","default":"seo_page_candidate"},"url":{"type":"string","title":"Url","description":"The page URL as the sitemap lists it."}},"additionalProperties":false,"type":"object","required":["url"],"title":"SeoPageCandidate","description":"A page the sitemap publishes that is not a tracked SEO page."},"SeoPageCandidateList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/SeoPageCandidate"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"True when more items exist past this page. Fetch them with a larger `offset`."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of items matching the query, across all pages."},"limit":{"type":"integer","minimum":1.0,"title":"Limit","description":"Page size that was applied."},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of items skipped before this page."},"published_count":{"type":"integer","minimum":0.0,"title":"Published Count","description":"Pages the sitemap read lists."},"tracked_count":{"type":"integer","minimum":0.0,"title":"Tracked Count","description":"Pages the brand tracks as SEO pages."},"count_is_partial":{"type":"boolean","title":"Count Is Partial","description":"True when the read stopped early (over 5000 pages or out of time): the site has more."}},"additionalProperties":false,"type":"object","required":["data","has_more","total","limit","offset","published_count","tracked_count","count_is_partial"],"title":"SeoPageCandidateList","description":"The untracked pages of the sitemap, in sitemap order.","example":{"count_is_partial":false,"data":[{"object":"seo_page_candidate","url":"https://www.rankprompt.com/blog/ai-visibility"}],"has_more":false,"limit":50,"object":"list","offset":0,"published_count":42,"total":1,"tracked_count":41}},"SeoPageCreate":{"properties":{"url":{"type":"string","title":"Url","description":"Public page URL to track (e.g. `https://rankprompt.com/pricing`)."},"label":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Label","description":"Optional human-friendly label."},"device":{"type":"string","enum":["mobile","desktop"],"title":"Device","description":"Device profile to audit under. One of `mobile`, `desktop`. Defaults to `mobile`.","default":"mobile"}},"additionalProperties":false,"type":"object","required":["url"],"title":"SeoPageCreate","description":"Add a page to track, whose URL must belong to a site you can audit (not a social or video platform)."},"SeoPageList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/SeoPage"},"type":"array","title":"Data"}},"additionalProperties":false,"type":"object","required":["data"],"title":"SeoPageList","description":"The brand's tracked pages, bounded per brand and not paginated."},"SeoPageUpdate":{"properties":{"label":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Label","description":"New human-friendly label."},"device":{"anyOf":[{"type":"string","enum":["mobile","desktop"]},{"type":"null"}],"title":"Device","description":"Change the device profile audits run under. One of `mobile`, `desktop`."}},"additionalProperties":false,"type":"object","title":"SeoPageUpdate","description":"Update a tracked page, changing only the fields you send."},"SeoRefreshCreate":{"properties":{"domains":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":20},{"type":"null"}],"title":"Domains","description":"Competitor domains to include; omit for the most mentioned few."}},"additionalProperties":false,"type":"object","title":"SeoRefreshCreate"},"SeoSchemaTemplates":{"properties":{"object":{"type":"string","const":"seo_schema_templates","title":"Object","description":"Always `seo_schema_templates`.","default":"seo_schema_templates"},"schemas":{"additionalProperties":true,"type":"object","title":"Schemas","description":"Templates keyed by type (e.g. `organization`, `website`, `faqpage`), each with `json` and `html`. With a linked Google Business Profile, `localbusiness` is the primary location and every other location is `localbusiness:<location_id>`."},"instructions":{"additionalProperties":{"type":"string"},"type":"object","title":"Instructions","description":"Short guidance keyed by the same template types, explaining where to paste each one."}},"additionalProperties":false,"type":"object","required":["schemas","instructions"],"title":"SeoSchemaTemplates","description":"Ready-to-paste schema.org (JSON-LD) templates for the brand, each with a copy-paste instruction."},"SeoTechnicalCheck":{"properties":{"object":{"type":"string","const":"seo_technical_check","title":"Object","description":"Always `seo_technical_check`.","default":"seo_technical_check"},"id":{"type":"string","title":"Id","description":"Technical check id (UUID)."},"page_id":{"type":"string","title":"Page Id","description":"Page this check belongs to (UUID)."},"brand_id":{"type":"string","title":"Brand Id","description":"Owning brand id (UUID)."},"status":{"type":"string","enum":["processing","completed","failed"],"title":"Status","description":"Check lifecycle state. One of `processing`, `completed`, `failed`."},"page_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Page Url","description":"URL that was checked."},"overall_score":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Overall Score","description":"Overall technical score 0-100, based on how many checks passed. Null when the page itself could not be read, for example behind a bot check; `page_fetch_error` says why."},"issues_count":{"type":"integer","minimum":0.0,"title":"Issues Count","description":"Number of issues found across all checks.","default":0},"passed_count":{"type":"integer","minimum":0.0,"title":"Passed Count","description":"Number of checks that passed.","default":0},"robots_txt":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Robots Txt","description":"Robots.txt findings."},"sitemap":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Sitemap","description":"Sitemap findings."},"meta_robots":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Meta Robots","description":"Meta robots directive findings."},"canonical":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Canonical","description":"Canonical URL findings."},"open_graph":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Open Graph","description":"Open Graph tag findings."},"twitter_card":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Twitter Card","description":"Twitter card findings."},"schema_org":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Schema Org","description":"Schema.org structured-data findings."},"indexability":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Indexability","description":"Overall indexability findings."},"ssl_certificate":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Ssl Certificate","description":"SSL certificate findings."},"redirect_chain":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Redirect Chain","description":"Redirect chain findings."},"internal_links":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Internal Links","description":"Internal link findings, including broken links."},"meta_content":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Meta Content","description":"Title and meta description findings."},"headings":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Headings","description":"Heading hierarchy findings."},"hreflang":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Hreflang","description":"Hreflang findings for international SEO."},"images":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Images","description":"Image alt-text coverage findings."},"security_headers":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Security Headers","description":"HTTP security header findings."},"page_weight":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Page Weight","description":"Page HTML weight findings."},"page_fetch_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Page Fetch Error","description":"Reason the page could not be fetched, if any."},"page_error_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Page Error Type","description":"Category of the fetch error, if any."},"page_fetch_warning":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Page Fetch Warning","description":"Note when the page was reachable only through a fallback path."},"page_warning_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Page Warning Type","description":"Category of the fetch warning, if any."},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message","description":"User-facing failure reason when `status` is `failed`."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the check was requested."},"started_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Started At","description":"When the check began running."},"finished_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Finished At","description":"When the check finished."},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Updated At","description":"When the check row was last updated."}},"additionalProperties":false,"type":"object","required":["id","page_id","brand_id","status","created_at"],"title":"SeoTechnicalCheck","description":"The latest technical SEO check for a page: an overall score plus a block of findings per category (robots.txt, sitemap, meta robots, canonical, Open Graph, Twitter card, schema.org, indexability, SSL, redirects, internal links, meta content, headings, hreflang, images, security headers, page weight)."},"SeoTechnicalSummary":{"properties":{"checked_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Checked At","description":"When the check finished."},"indexability":{"anyOf":[{"type":"string","enum":["indexable","indexable_with_warnings","blocked"]},{"type":"null"}],"title":"Indexability","description":"Whether search engines can index the page."},"ai_bots_blocked":{"items":{"type":"string"},"type":"array","title":"Ai Bots Blocked","description":"AI crawlers the site's robots.txt blocks, by name (for example `GPTBot`)."},"ai_bots_checked":{"type":"integer","title":"Ai Bots Checked","description":"How many AI crawlers robots.txt was checked for.","default":0},"structured_data_types":{"items":{"type":"string"},"type":"array","title":"Structured Data Types","description":"schema.org types found on the page (for example `Article`)."},"issues_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Issues Count","description":"Technical issues the check found."}},"additionalProperties":false,"type":"object","title":"SeoTechnicalSummary","description":"The page's latest completed technical check, in brief; the full check is at `/technical-checks`."},"SequenceResults":{"properties":{"steps":{"items":{"$ref":"#/components/schemas/SequenceStepResults"},"type":"array","title":"Steps","description":"Per step, in order."},"total_emails":{"type":"integer","minimum":0.0,"title":"Total Emails","description":"Emails the sequence created."},"total_replied":{"type":"integer","minimum":0.0,"title":"Total Replied","description":"Of those, replied to."},"conversion_rate":{"type":"number","title":"Conversion Rate","description":"Replied over created, in percent."}},"additionalProperties":false,"type":"object","required":["total_emails","total_replied","conversion_rate"],"title":"SequenceResults","description":"How the sequence performs."},"SequenceStep":{"properties":{"id":{"type":"string","maxLength":100,"title":"Id","description":"Step id, unique in the sequence; links point to it."},"type":{"type":"string","enum":["email","wait","condition"],"title":"Type","description":"`email`, `wait` or `condition`."},"order":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Order","description":"Position; the first step must be an email."},"next_step_id":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Next Step Id","description":"The step after an email or a wait."},"on_true_step_id":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"On True Step Id","description":"A condition's step when it holds."},"on_false_step_id":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"On False Step Id","description":"A condition's step when it does not hold by the timeout."},"template_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Template Id","description":"An email step's template."},"subject_override":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Subject Override","description":"An email step's own subject."},"body_override":{"anyOf":[{"type":"string","maxLength":100000},{"type":"null"}],"title":"Body Override","description":"An email step's own HTML body."},"wait_days":{"anyOf":[{"type":"integer","maximum":365.0,"minimum":1.0},{"type":"null"}],"title":"Wait Days","description":"A wait step's days; required for a wait."},"condition_type":{"anyOf":[{"type":"string","enum":["opened","replied"]},{"type":"null"}],"title":"Condition Type","description":"A condition's test; required for a condition."},"condition_timeout_days":{"anyOf":[{"type":"integer","maximum":30.0,"minimum":0.0},{"type":"null"}],"title":"Condition Timeout Days","description":"Days a condition waits before taking `on_false_step_id`."},"notify_on_true":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Notify On True","description":"Notify the team when the condition holds."}},"additionalProperties":false,"type":"object","required":["id","type","order"],"title":"SequenceStep","description":"One node of a sequence: an email, a wait, or a branch on whether the last email was opened or replied to."},"SequenceStepResults":{"properties":{"step_id":{"type":"string","title":"Step Id","description":"Step id."},"step_type":{"type":"string","enum":["email","wait","condition"],"title":"Step Type","description":"Step type."},"order":{"type":"integer","title":"Order","description":"Step position."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Emails that reached the step."},"completed":{"type":"integer","minimum":0.0,"title":"Completed","description":"An email step's emails that went out."},"opened_count":{"type":"integer","minimum":0.0,"title":"Opened Count","description":"An email step's emails opened."},"replied_count":{"type":"integer","minimum":0.0,"title":"Replied Count","description":"An email step's emails replied to."},"true_count":{"type":"integer","minimum":0.0,"title":"True Count","description":"A condition's contacts that met it."},"false_count":{"type":"integer","minimum":0.0,"title":"False Count","description":"A condition's contacts that did not by the timeout."}},"additionalProperties":false,"type":"object","required":["step_id","step_type","order","total","completed","opened_count","replied_count","true_count","false_count"],"title":"SequenceStepResults","description":"How one step performs across the sequence's emails."},"SerpAiOverview":{"properties":{"loaded":{"type":"boolean","title":"Loaded","description":"False when Google streamed the AI Overview after the page, so its sources are unknown."},"cites_brand":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Cites Brand","description":"One of the AI Overview's sources is on the brand's website; null when the sources were not captured."},"names_brand":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Names Brand","description":"The AI Overview's text names the brand or one of its aliases, whether or not it cites the brand. Only a keyword's history carries it; null elsewhere and when the text was not captured."},"references":{"anyOf":[{"items":{"$ref":"#/components/schemas/SerpSource"},"type":"array"},{"type":"null"}],"title":"References","description":"The pages the AI Overview cited. Only a keyword's history carries them; null elsewhere."},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Text","description":"The AI Overview's text as Google wrote it. Only a keyword's history carries it; null elsewhere."}},"type":"object","required":["loaded","cites_brand"],"title":"SerpAiOverview"},"SerpDiscussion":{"properties":{"url":{"type":"string","title":"Url","description":"The thread's URL."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"The thread's title as Google showed it."},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source","description":"The site as Google names it (e.g. `Reddit`, `Quora`)."},"posts_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Posts Count","description":"Posts in the thread, when Google shows it."},"source_type":{"type":"string","enum":["reddit","qa_forum","linkedin"],"title":"Source Type","description":"The kind of thread, as Community files it: `reddit`, `qa_forum` or `linkedin`."},"group_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Group Key","description":"The subreddit, forum host or LinkedIn handle."}},"type":"object","required":["url","source_type"],"title":"SerpDiscussion","description":"A Reddit, Q&A or forum thread on the page, organic or in the Discussions and forums block."},"SerpFeaturedSnippet":{"properties":{"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain","description":"The site of the page Google quotes."},"url":{"type":"string","title":"Url","description":"The page's URL, or Google's own redirect when Google hid the page behind it."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"The page's title as Google showed it."},"is_brand":{"type":"boolean","title":"Is Brand","description":"The featured snippet comes from the brand's website."}},"type":"object","required":["url","is_brand"],"title":"SerpFeaturedSnippet"},"SerpResult":{"properties":{"position":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Position"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"The page; null when Google hid it behind its own redirect (`domain` still says whose)."},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain","description":"The site of the result."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"}},"type":"object","title":"SerpResult"},"SerpSource":{"properties":{"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain","description":"The page's domain."},"url":{"type":"string","title":"Url","description":"The page's URL."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"The page's title as Google showed it."}},"type":"object","required":["url"],"title":"SerpSource","description":"A page Google took something from."},"SerpVideo":{"properties":{"url":{"type":"string","title":"Url","description":"The video's URL."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"The video's title as Google showed it."},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source","description":"Platform and channel as Google shows them."},"published_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Published At","description":"When the video was published, when shown."}},"type":"object","required":["url"],"title":"SerpVideo","description":"A video in the page's video carousel."},"SerpView":{"properties":{"object":{"type":"string","const":"serp_snapshot","title":"Object","description":"Always `serp_snapshot`.","default":"serp_snapshot"},"keyword":{"type":"string","title":"Keyword"},"cached":{"type":"boolean","title":"Cached","description":"Served from a page a check read in the last 20 hours, at no cost."},"credits_charged":{"type":"integer","title":"Credits Charged"},"found":{"type":"boolean","title":"Found","description":"Google returned a page; when false nothing was charged."},"position":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Position","description":"The brand's position in the top ten, if it is there."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"The brand's page in the top ten; null when it is not there or Google hid the page behind its own redirect."},"top_results":{"items":{"$ref":"#/components/schemas/SerpViewResult"},"type":"array","title":"Top Results"},"serp":{"anyOf":[{"$ref":"#/components/schemas/KeywordSerp"},{"type":"null"}],"description":"People also ask, related searches, the AI Overview with its sources, threads, videos."},"saved":{"type":"boolean","title":"Saved","description":"The keyword was new and is now saved to the library, without rank checks."}},"type":"object","required":["keyword","cached","credits_charged","found","saved"],"title":"SerpView","description":"A keyword's Google page: the top ten, the brand's place in it and what surrounds the results."},"SerpViewCreate":{"properties":{"keyword":{"type":"string","maxLength":200,"minLength":1,"title":"Keyword"}},"type":"object","required":["keyword"],"title":"SerpViewCreate","description":"A keyword whose Google page to read now, in the brand's market."},"SerpViewResult":{"properties":{"position":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Position"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"The page; null when Google hid it behind its own redirect (`domain` still says whose)."},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain","description":"The site of the result."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"is_brand":{"type":"boolean","title":"Is Brand","description":"The result is one of the brand's own pages.","default":false}},"type":"object","title":"SerpViewResult"},"ShareWhiteLabel":{"properties":{"logo_url":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Logo Url"},"company_name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Company Name"},"primary_color":{"anyOf":[{"type":"string","maxLength":7,"minLength":7,"pattern":"^#[0-9A-Fa-f]{6}$"},{"type":"null"}],"title":"Primary Color","description":"`#RRGGBB` brand color."},"secondary_color":{"anyOf":[{"type":"string","maxLength":7,"minLength":7,"pattern":"^#[0-9A-Fa-f]{6}$"},{"type":"null"}],"title":"Secondary Color"},"footer_email":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Footer Email","description":"Contact email rendered in the share footer."},"footer_website":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Footer Website"}},"additionalProperties":false,"type":"object","title":"ShareWhiteLabel","description":"White-label branding applied to a share, resolved from the caller's account settings.","example":{"footer_email":"support@e2e.test","logo_url":"https://e2e.test/share-logo.png","primary_color":"#C0392B"}},"SharedChange":{"properties":{"delta":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Delta","description":"Change in points over the shared answers; null when they share none."},"same":{"type":"boolean","title":"Same","description":"True when both runs asked exactly the same answers."},"shared_answers":{"type":"integer","minimum":0.0,"title":"Shared Answers","description":"Answers both runs asked."},"new_prompts":{"type":"integer","minimum":0.0,"title":"New Prompts","description":"Prompts only the newer run asked, left out of the delta."},"dropped_prompts":{"type":"integer","minimum":0.0,"title":"Dropped Prompts","description":"Prompts only the older run asked, left out of the delta."}},"additionalProperties":false,"type":"object","required":["same","shared_answers","new_prompts","dropped_prompts"],"title":"SharedChange","description":"A run against the run before it, counted only over the answers both asked."},"SitePage":{"properties":{"object":{"type":"string","const":"site_page","title":"Object","default":"site_page"},"url":{"type":"string","title":"Url"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"The page's title; null until the page is read."},"clicks":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Clicks","description":"Google clicks from the newest Search Console fetch; null without one."},"impressions":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Impressions","description":"Google impressions from the newest Search Console fetch; null without one."}},"additionalProperties":false,"type":"object","required":["url"],"title":"SitePage","description":"One indexed page of the brand's site, with its Google numbers when Search Console is cached."},"SitePageList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/SitePage"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"True when more items exist past this page. Fetch them with a larger `offset`."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of items matching the query, across all pages."},"limit":{"type":"integer","minimum":1.0,"title":"Limit","description":"Page size that was applied."},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of items skipped before this page."}},"additionalProperties":false,"type":"object","required":["data","has_more","total","limit","offset"],"title":"SitePageList","description":"A page of the brand's site index, the most clicked first, then by title."},"SocialCitation":{"properties":{"object":{"type":"string","const":"social_citation","title":"Object","description":"Always `social_citation`.","default":"social_citation"},"network":{"type":"string","enum":["reddit","youtube","linkedin"],"title":"Network","description":"`reddit`, `youtube` or `linkedin`, the `network` asked for."},"url":{"type":"string","title":"Url","description":"The cited URL. A video cited under several URLs is one row."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"Post or video title, when known."},"citation_count":{"type":"integer","minimum":0.0,"title":"Citation Count","description":"Times the answers cited it in the filtered window."},"prompt_count":{"type":"integer","minimum":0.0,"title":"Prompt Count","description":"Distinct prompts whose answers cited it."},"platforms":{"items":{"type":"string"},"type":"array","title":"Platforms","description":"Engines that cited it (an open set, e.g. `chatgpt`, `perplexity`)."},"last_seen_at":{"type":"string","format":"date-time","title":"Last Seen At","description":"When an answer last cited it."},"subreddit":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subreddit","description":"Reddit: the subreddit, without `r/`."},"reddit_post_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reddit Post Id","description":"Reddit: the post id."},"youtube_video_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Youtube Video Id","description":"YouTube: the video id."},"youtube_channel":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Youtube Channel","description":"YouTube: the channel id or handle in the URL."},"linkedin_kind":{"anyOf":[{"type":"string","enum":["post","article","person","company","school","showcase","other"]},{"type":"null"}],"title":"Linkedin Kind","description":"LinkedIn: `post`, `article`, `person`, `company`, `school`, `showcase` or `other` (any other LinkedIn page); an open set, new values can appear."},"linkedin_handle":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Linkedin Handle","description":"LinkedIn: the company, school, page or member handle, decoded (`josé`, not `jos%C3%A9`)."},"channel_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Channel Title","description":"YouTube: the channel name."},"channel_handle":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Channel Handle","description":"YouTube: the channel handle."},"published_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"format":"date-time","title":"Published At","description":"When the post or video was published: YouTube's date for a video, else the date the post's page gives; `null` when unknown."},"duration_seconds":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Duration Seconds","description":"YouTube: video length in seconds."},"view_count":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"View Count","description":"YouTube: views."},"like_count":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Like Count","description":"YouTube: likes."},"comment_count":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Comment Count","description":"YouTube: comments."},"subscriber_count":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Subscriber Count","description":"YouTube: channel subscribers."},"author":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Author","description":"The person the page names as its author, `null` when it names none or was not read yet."},"image_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Url","description":"The page's preview image (`og:image` or the engine's thumbnail), `null` until the page is read."}},"additionalProperties":false,"type":"object","required":["network","url","citation_count","prompt_count","platforms","last_seen_at"],"title":"SocialCitation","description":"One Reddit post, YouTube video or LinkedIn post or page the answers cited.","example":{"citation_count":14,"last_seen_at":"2026-09-20T08:15:00+00:00","network":"reddit","object":"social_citation","platforms":["chatgpt","perplexity"],"prompt_count":6,"reddit_post_id":"1c2x9aa","subreddit":"running","title":"Best daily trainer under $150?","url":"https://www.reddit.com/r/running/comments/1c2x9aa/best_daily_trainer_under_150/"}},"SocialCitationList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/SocialCitation"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"True when more items exist past this page. Fetch them with a larger `offset`."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of items matching the query, across all pages."},"limit":{"type":"integer","minimum":1.0,"title":"Limit","description":"Page size that was applied."},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of items skipped before this page."}},"additionalProperties":false,"type":"object","required":["data","has_more","total","limit","offset"],"title":"SocialCitationList","description":"A page of cited social posts, most cited first.","example":{"data":[{"citation_count":14,"last_seen_at":"2026-09-20T08:15:00+00:00","network":"reddit","object":"social_citation","platforms":["chatgpt","perplexity"],"prompt_count":6,"reddit_post_id":"1c2x9aa","subreddit":"running","title":"Best daily trainer under $150?","url":"https://www.reddit.com/r/running/comments/1c2x9aa/best_daily_trainer_under_150/"}],"has_more":false,"limit":100,"object":"list","offset":0,"total":1}},"SocialGroup":{"properties":{"object":{"type":"string","const":"social_group","title":"Object","description":"Always `social_group`.","default":"social_group"},"network":{"type":"string","enum":["reddit","youtube","linkedin"],"title":"Network","description":"`reddit`, `youtube` or `linkedin`, the `network` asked for."},"key":{"type":"string","title":"Key","description":"Grouping key; for Reddit the subreddit without `r/`, which the social list takes as `subreddit`."},"label":{"type":"string","title":"Label","description":"Display name: the subreddit, the channel title or the author handle."},"linkedin_kind":{"anyOf":[{"type":"string","enum":["person","company","school","showcase"]},{"type":"null"}],"title":"Linkedin Kind","description":"LinkedIn: who the author is, `person`, `company`, `school` or `showcase`; a post's author is an organization when its handle is cited as one. An open set, new values can appear."},"item_count":{"type":"integer","minimum":0.0,"title":"Item Count","description":"Distinct cited posts, videos or pages from it."},"citation_count":{"type":"integer","minimum":0.0,"title":"Citation Count","description":"Times the answers cited them in the filtered window."},"prompt_count":{"type":"integer","minimum":0.0,"title":"Prompt Count","description":"Distinct prompts whose answers cited them."},"last_seen_at":{"type":"string","format":"date-time","title":"Last Seen At","description":"When an answer last cited one of them."},"channel_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Channel Title","description":"YouTube: the channel name."},"channel_handle":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Channel Handle","description":"YouTube: the channel handle."},"channel_thumbnail_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Channel Thumbnail Url","description":"YouTube: the channel picture."},"subscriber_count":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Subscriber Count","description":"YouTube: channel subscribers."},"view_count":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"View Count","description":"YouTube: views of the cited videos, summed."}},"additionalProperties":false,"type":"object","required":["network","key","label","item_count","citation_count","prompt_count","last_seen_at"],"title":"SocialGroup","description":"A subreddit, a YouTube channel or a LinkedIn author, with what the answers cited from it.","example":{"citation_count":23,"item_count":7,"key":"running","label":"running","last_seen_at":"2026-09-20T08:15:00+00:00","network":"reddit","object":"social_group","prompt_count":9}},"SocialGroupList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/SocialGroup"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"True when more items exist past this page. Fetch them with a larger `offset`."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of items matching the query, across all pages."},"limit":{"type":"integer","minimum":1.0,"title":"Limit","description":"Page size that was applied."},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of items skipped before this page."},"total_items":{"type":"integer","minimum":0.0,"title":"Total Items","description":"Cited posts, videos or pages across every group."},"total_citations":{"type":"integer","minimum":0.0,"title":"Total Citations","description":"Their citations across every group."}},"additionalProperties":false,"type":"object","required":["data","has_more","total","limit","offset","total_items","total_citations"],"title":"SocialGroupList","description":"A page of subreddits, channels or authors, most cited first, with the window's totals.","example":{"data":[{"citation_count":23,"item_count":7,"key":"running","label":"running","last_seen_at":"2026-09-20T08:15:00+00:00","network":"reddit","object":"social_group","prompt_count":9}],"has_more":false,"limit":100,"object":"list","offset":0,"total":1,"total_citations":23,"total_items":7}},"SourcePromptProgress":{"properties":{"object":{"type":"string","const":"source_prompt_progress","title":"Object","default":"source_prompt_progress"},"prompt_text":{"type":"string","title":"Prompt Text"},"missed_before":{"items":{"type":"string"},"type":"array","title":"Missed Before","description":"Engines that did not name the brand when the article was written."},"missed_now":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Missed Now","description":"Engines that still do not. Null when no report has run this prompt since."},"recovered":{"items":{"type":"string"},"type":"array","title":"Recovered","description":"Engines that name the brand again. This is the win, engine by engine."},"not_run":{"items":{"type":"string"},"type":"array","title":"Not Run","description":"Engines the newer report did not ask, so they are neither back nor missing."},"cites_article":{"type":"boolean","title":"Cites Article","description":"The newest answer links this very article.","default":false},"checked_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Checked At","description":"When that newest answer ran."}},"additionalProperties":false,"type":"object","required":["prompt_text"],"title":"SourcePromptProgress","description":"What happened to one of the prompts the article was written to answer."},"SubscriptionCheckout":{"properties":{"object":{"type":"string","const":"subscription_checkout","title":"Object","description":"Always `subscription_checkout`.","default":"subscription_checkout"},"status":{"type":"string","enum":["checkout","succeeded","already_subscribed"],"title":"Status","description":"`checkout` when nothing was charged yet and the buyer must open `checkout_url`; repeating the call returns that same link while it is open. `succeeded` once the buyer paid it and the plan is active. `already_subscribed` when the account already holds a plan: changing plans happens at `manage_url`."},"plan":{"type":"string","enum":["starter","pro","agency","agency_plus"],"title":"Plan","description":"The plan asked for."},"interval":{"type":"string","enum":["month","year"],"title":"Interval","description":"The billing interval asked for."},"amount_cents":{"type":"integer","minimum":0.0,"title":"Amount Cents","description":"Price per interval in the smallest currency unit, before any trial."},"currency":{"type":"string","title":"Currency","description":"ISO 4217 code, lowercase."},"trial_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Trial Days","description":"Free days before the first charge, on `checkout`. 0 when no trial applies."},"first_charge_cents":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"First Charge Cents","description":"What the first charge will be, on `checkout`: `amount_cents` less the first-month offer when one applies, before tax."},"checkout_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Checkout Url","description":"Where the buyer subscribes, on `checkout`."},"checkout_session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Checkout Session Id","description":"The Stripe Checkout session."},"subscription_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subscription Id","description":"The new Stripe subscription, on `succeeded`."},"current_plan":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Current Plan","description":"The plan already held, on `already_subscribed`."},"manage_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Manage Url","description":"Where to change plans, on `already_subscribed`."}},"additionalProperties":false,"type":"object","required":["status","plan","interval","amount_cents","currency"],"title":"SubscriptionCheckout","description":"Where a new subscription stands: waiting on Checkout, paid, or not needed.","example":{"amount_cents":8900,"checkout_session_id":"cs_live_...","checkout_url":"https://checkout.stripe.com/c/pay/cs_live_...","currency":"usd","first_charge_cents":8900,"interval":"month","object":"subscription_checkout","plan":"pro","status":"checkout","trial_days":0}},"SubscriptionRequest":{"properties":{"plan":{"type":"string","enum":["starter","pro","agency","agency_plus"],"title":"Plan","description":"The plan to subscribe to."},"interval":{"type":"string","enum":["month","year"],"title":"Interval","description":"Bill monthly or yearly.","default":"month"}},"additionalProperties":false,"type":"object","required":["plan"],"title":"SubscriptionRequest","description":"Start a subscription to a dashboard plan.","example":{"interval":"month","plan":"pro"}},"Task":{"properties":{"object":{"type":"string","const":"task","title":"Object","description":"Always `task`.","default":"task"},"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id","description":"Task id (UUID). `null` for tasks returned inline from a cached AI suggestion."},"brand_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brand Id","description":"Owning brand id (UUID)."},"title":{"type":"string","title":"Title","description":"Short task title."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Task detail."},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category","description":"Task category. One of `CONTENT`, `TECHNICAL`, `OUTREACH`, `KNOWLEDGE`, `MONITORING`, `SEO`."},"priority":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Priority","description":"Priority. One of `high`, `medium`, `low`."},"effort_level":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Effort Level","description":"Estimated effort. One of `low`, `medium`, `high`."},"estimated_impact":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Estimated Impact","description":"Estimated impact, e.g. `high` or a short phrase."},"action_items":{"items":{"type":"string"},"type":"array","title":"Action Items","description":"Concrete steps to complete the task."},"action_items_done":{"items":{"type":"string"},"type":"array","title":"Action Items Done","description":"The action items ticked off, by their text; always a subset of `action_items`."},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status","description":"Workflow status (board column). One of `suggested` (a finding waiting to be accepted), `backlog`, `in_progress`, `review`, `approved`, `done`, `dismissed` (declined; it is not suggested again). A `suggested` task untouched for 90 days is deleted nightly."},"due_date":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Due Date","description":"When the task is due, if set."},"report_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Report Id","description":"Report this task was generated from, if any."},"brief_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brief Id","description":"Linked content brief id, if any."},"content_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content Type","description":"Content type of the linked brief, if any."},"source_type":{"anyOf":[{"type":"string","enum":["brand_audit","report","seo_audit","technical_audit","manual","content_brief","search_console","content_opportunity","rank_check","gbp_audit","youtube","site_pilot"]},{"type":"null"}],"title":"Source Type","description":"What generated the task. `rank_check` is a keyword that fell 5 or more positions (or out of the top 100) in a scheduled rank check, with the page that ranked in `external_url`, or one site task when many fall in the same run."},"external_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Url","description":"Linked external URL (e.g. a PR), if any."},"pr_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pr Url","description":"URL of the GitHub PR opened for this task, if any."},"agent_session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Session Id","description":"Agent session working on this task, if any."},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Completed At","description":"When the task was completed, if done."},"archived_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Archived At","description":"When the task was archived, if archived."},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Created At","description":"When the task was created."},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Updated At","description":"When the task row was last updated."}},"additionalProperties":false,"type":"object","required":["title"],"title":"Task","description":"A work item generated for the brand (e.g. by an AI suggestion).","example":{"action_items":["Draft the outline","Add a feature matrix"],"brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","category":"CONTENT","created_at":"2026-07-01T10:00:00+00:00","description":"AI answers keep surfacing a rival; a head-to-head page closes the gap.","effort_level":"medium","estimated_impact":"high","id":"a1b2c3d4-1234-4abc-9def-0123456789ab","object":"task","priority":"high","report_id":"c4f8b6a2-9a17-4e31-92fa-7d1e3b5c8b2a","source_type":"report","status":"backlog","title":"Publish a comparison page targeting your top competitor","updated_at":"2026-07-01T10:00:00+00:00"}},"TaskCreate":{"properties":{"title":{"type":"string","maxLength":500,"minLength":1,"title":"Title","description":"Short task title."},"description":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}],"title":"Description","description":"Longer task detail."},"category":{"anyOf":[{"type":"string","enum":["CONTENT","TECHNICAL","OUTREACH","KNOWLEDGE","MONITORING","SEO","LOCAL"]},{"type":"null"}],"title":"Category","description":"Task category (e.g. `CONTENT`, `TECHNICAL`, `OUTREACH`, `SEO`)."},"priority":{"type":"string","enum":["high","medium","low"],"title":"Priority","description":"Priority. One of `high`, `medium`, `low`.","default":"medium"},"effort_level":{"anyOf":[{"type":"string","enum":["high","medium","low"]},{"type":"null"}],"title":"Effort Level","description":"Estimated effort. `low`, `medium`, or `high`."},"estimated_impact":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Estimated Impact","description":"Short note on expected impact."},"action_items":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":20},{"type":"null"}],"title":"Action Items","description":"Concrete steps to complete the task."},"due_date":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Due Date","description":"Due date (UTC ISO-8601), if any."},"external_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Url","description":"Link to related work (e.g. a pull request)."},"report_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Report Id","description":"Report this task relates to, if any."}},"additionalProperties":false,"type":"object","required":["title"],"title":"TaskCreate","description":"Create a task (work item) for a brand."},"TaskDetail":{"properties":{"object":{"type":"string","const":"task","title":"Object","description":"Always `task`.","default":"task"},"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id","description":"Task id (UUID). `null` for tasks returned inline from a cached AI suggestion."},"brand_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brand Id","description":"Owning brand id (UUID)."},"title":{"type":"string","title":"Title","description":"Short task title."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Task detail."},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category","description":"Task category. One of `CONTENT`, `TECHNICAL`, `OUTREACH`, `KNOWLEDGE`, `MONITORING`, `SEO`."},"priority":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Priority","description":"Priority. One of `high`, `medium`, `low`."},"effort_level":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Effort Level","description":"Estimated effort. One of `low`, `medium`, `high`."},"estimated_impact":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Estimated Impact","description":"Estimated impact, e.g. `high` or a short phrase."},"action_items":{"items":{"type":"string"},"type":"array","title":"Action Items","description":"Concrete steps to complete the task."},"action_items_done":{"items":{"type":"string"},"type":"array","title":"Action Items Done","description":"The action items ticked off, by their text; always a subset of `action_items`."},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status","description":"Workflow status (board column). One of `suggested` (a finding waiting to be accepted), `backlog`, `in_progress`, `review`, `approved`, `done`, `dismissed` (declined; it is not suggested again). A `suggested` task untouched for 90 days is deleted nightly."},"due_date":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Due Date","description":"When the task is due, if set."},"report_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Report Id","description":"Report this task was generated from, if any."},"brief_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brief Id","description":"Linked content brief id, if any."},"content_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content Type","description":"Content type of the linked brief, if any."},"source_type":{"anyOf":[{"type":"string","enum":["brand_audit","report","seo_audit","technical_audit","manual","content_brief","search_console","content_opportunity","rank_check","gbp_audit","youtube","site_pilot"]},{"type":"null"}],"title":"Source Type","description":"What generated the task. `rank_check` is a keyword that fell 5 or more positions (or out of the top 100) in a scheduled rank check, with the page that ranked in `external_url`, or one site task when many fall in the same run."},"external_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Url","description":"Linked external URL (e.g. a PR), if any."},"pr_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pr Url","description":"URL of the GitHub PR opened for this task, if any."},"agent_session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Session Id","description":"Agent session working on this task, if any."},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Completed At","description":"When the task was completed, if done."},"archived_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Archived At","description":"When the task was archived, if archived."},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Created At","description":"When the task was created."},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Updated At","description":"When the task row was last updated."},"source":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Source","description":"What the task came from, read when you ask: `type` is `report` (score, engines, prompt categories, up to ten prompts, top competitors), `brand_audit` (mention and sentiment per engine, key themes), `seo` (the tracked pages with their stored scores) or `content_brief` (the linked article, its client review and an excerpt). `null` for a manual task or a source that is gone."}},"additionalProperties":false,"type":"object","required":["title"],"title":"TaskDetail","description":"One task with a snapshot of where it came from.","example":{"action_items":["Draft the outline","Add a feature matrix"],"brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","category":"CONTENT","created_at":"2026-07-01T10:00:00+00:00","description":"AI answers keep surfacing a rival; a head-to-head page closes the gap.","effort_level":"medium","estimated_impact":"high","id":"a1b2c3d4-1234-4abc-9def-0123456789ab","object":"task","priority":"high","report_id":"c4f8b6a2-9a17-4e31-92fa-7d1e3b5c8b2a","source_type":"report","status":"backlog","title":"Publish a comparison page targeting your top competitor","updated_at":"2026-07-01T10:00:00+00:00"}},"TaskList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/Task"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Opaque continuation token. Pass back as `?cursor=` to fetch the next page. `null` when `has_more` is false."}},"additionalProperties":false,"type":"object","required":["data","has_more"],"title":"TaskList","description":"A cursor-paginated page of tasks.","example":{"data":[{"action_items":["Draft the outline","Add a feature matrix"],"brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","category":"CONTENT","created_at":"2026-07-01T10:00:00+00:00","description":"AI answers keep surfacing a rival; a head-to-head page closes the gap.","effort_level":"medium","estimated_impact":"high","id":"a1b2c3d4-1234-4abc-9def-0123456789ab","object":"task","priority":"high","report_id":"c4f8b6a2-9a17-4e31-92fa-7d1e3b5c8b2a","source_type":"report","status":"backlog","title":"Publish a comparison page targeting your top competitor","updated_at":"2026-07-01T10:00:00+00:00"}],"has_more":false,"object":"list"}},"TaskSummary":{"properties":{"object":{"type":"string","const":"task_summary","title":"Object","description":"Always `task_summary`.","default":"task_summary"},"by_status":{"additionalProperties":{"type":"integer"},"type":"object","title":"By Status","description":"Task counts keyed by workflow status."},"by_priority":{"additionalProperties":{"type":"integer"},"type":"object","title":"By Priority","description":"Task counts keyed by priority."}},"additionalProperties":false,"type":"object","required":["by_status","by_priority"],"title":"TaskSummary","description":"Aggregated task counts for a brand, bucketed by status and priority.","example":{"by_priority":{"high":3,"low":3,"medium":6},"by_status":{"backlog":4,"done":7,"in_progress":1},"object":"task_summary"}},"TaskUpdate":{"properties":{"title":{"anyOf":[{"type":"string","maxLength":500,"minLength":1},{"type":"null"}],"title":"Title","description":"New title."},"description":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}],"title":"Description","description":"New detail."},"category":{"anyOf":[{"type":"string","enum":["CONTENT","TECHNICAL","OUTREACH","KNOWLEDGE","MONITORING","SEO","LOCAL"]},{"type":"null"}],"title":"Category","description":"Reclassify the task."},"priority":{"anyOf":[{"type":"string","enum":["high","medium","low"]},{"type":"null"}],"title":"Priority","description":"Change priority."},"effort_level":{"anyOf":[{"type":"string","enum":["high","medium","low"]},{"type":"null"}],"title":"Effort Level","description":"Change the effort estimate."},"estimated_impact":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Estimated Impact","description":"Change the impact note."},"action_items":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":20},{"type":"null"}],"title":"Action Items","description":"Replace the action items."},"action_items_done":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":20},{"type":"null"}],"title":"Action Items Done","description":"Replace which action items are ticked off, by their text. A text that is not one of the task's `action_items` is ignored; replacing `action_items` drops the ticks of items that no longer exist."},"status":{"anyOf":[{"type":"string","enum":["backlog","in_progress","review","approved","done","dismissed"]},{"type":"null"}],"title":"Status","description":"Move the task: `backlog`, `in_progress`, `review`, `approved`, `done` or `dismissed`. Accept a suggestion with `backlog`, decline it with `dismissed`; a task never moves back to `suggested`."},"due_date":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Due Date","description":"Change the due date (UTC ISO-8601)."},"external_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Url","description":"Change the related-work link."}},"additionalProperties":false,"type":"object","title":"TaskUpdate","description":"Update a task, changing only the fields you send."},"TrackPages":{"properties":{"urls":{"items":{"type":"string"},"type":"array","maxItems":100,"minItems":1,"title":"Urls","description":"Public page URLs, up to 100."}},"additionalProperties":false,"type":"object","required":["urls"],"title":"TrackPages","description":"Pages to follow.","example":{"urls":["https://www.rankprompt.com/blog/ai-visibility"]}},"TrackedKeyword":{"properties":{"object":{"type":"string","const":"tracked_keyword","title":"Object","description":"Always `tracked_keyword`.","default":"tracked_keyword"},"id":{"type":"string","title":"Id"},"keyword":{"type":"string","title":"Keyword"},"source":{"type":"string","enum":["manual","gsc","prompt","research","ranked","gap","fanout","serp","copilot"],"title":"Source","description":"Where the keyword came from."},"rank_tracked":{"type":"boolean","title":"Rank Tracked","description":"Rank checks run for it and it counts against the plan's tracking cap; `false` is a saved keyword, free and uncapped.","default":true},"starred":{"type":"boolean","title":"Starred","description":"Starred on the Keywords page.","default":false},"opportunity_score":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Opportunity Score","description":"The Keywords page's own 0 to 100 score (volume, difficulty against what the site already ranks for, position, intent, AI Overview), halved once an article targets the keyword. Content opportunities score differently. Null until scored."},"opportunity_tier":{"anyOf":[{"type":"string","enum":["high","medium","low"]},{"type":"null"}],"title":"Opportunity Tier","description":"`high` from 65, `medium` from 40, else `low`."},"article":{"anyOf":[{"$ref":"#/components/schemas/KeywordArticle"},{"type":"null"}],"description":"The newest article targeting it."},"cluster":{"anyOf":[{"$ref":"#/components/schemas/KeywordClusterRef"},{"type":"null"}],"description":"The topic cluster it sits in; null when it stands alone or clusters were never built."},"target_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Url","description":"The page that should rank for it."},"last_position":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Last Position","description":"Google position at the last check; null when outside the top 100, or never checked."},"previous_position":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Previous Position","description":"Position at the check before."},"best_position":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Best Position","description":"Best position ever seen."},"change":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Change","description":"Positions gained since the previous check; positive is better."},"last_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Url","description":"The brand's page Google ranked at the last check; null when Google hid the page behind its own redirect."},"last_checked_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Last Checked At"},"last_check_failed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Last Check Failed At","description":"Set when the provider could not answer the last check."},"checking":{"type":"boolean","title":"Checking","description":"A rank check is queued and has not landed yet.","default":false},"metrics":{"anyOf":[{"$ref":"#/components/schemas/KeywordMetrics"},{"type":"null"}]},"serp":{"anyOf":[{"$ref":"#/components/schemas/KeywordSerp"},{"type":"null"}],"description":"The Google page around the keyword, shared by every brand tracking it in this market; null until any rank check there has read it. `checked_at` says when."},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Created At"}},"type":"object","required":["id","keyword","source"],"title":"TrackedKeyword","description":"A keyword in the brand's library, with its last position when it is rank tracked."},"TrackedKeywordList":{"properties":{"object":{"type":"string","const":"tracked_keyword_list","title":"Object","default":"tracked_keyword_list"},"data":{"items":{"$ref":"#/components/schemas/TrackedKeyword"},"type":"array","title":"Data"},"total":{"type":"integer","title":"Total","description":"Keywords matching the filters, across every page."},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"has_more":{"type":"boolean","title":"Has More"},"summary":{"$ref":"#/components/schemas/KeywordSummary"},"limits":{"$ref":"#/components/schemas/KeywordLimits"},"target":{"$ref":"#/components/schemas/KeywordTarget"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain","description":"The brand's site the positions are for."}},"type":"object","required":["data","total","limit","offset","has_more","summary","limits","target"],"title":"TrackedKeywordList","description":"A page of the keyword library, with totals and plan limits."},"TrackedPage":{"properties":{"object":{"type":"string","const":"tracked_page","title":"Object","description":"Always `tracked_page`.","default":"tracked_page"},"id":{"type":"string","title":"Id"},"url":{"type":"string","title":"Url"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"citations":{"type":"integer","minimum":0.0,"title":"Citations","default":0},"prompt_count":{"type":"integer","minimum":0.0,"title":"Prompt Count","default":0},"platforms":{"items":{"type":"string"},"type":"array","title":"Platforms"},"avg_position":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Position"},"first_half":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"First Half","description":"Citations in the first half of the runs read."},"second_half":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Second Half","description":"Citations in the second half of the runs read."},"last_seen":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"format":"date-time","title":"Last Seen"},"source_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Type","description":"`owned` (the brand's own site), `competitor` (a registered competitor's), else the kind of site (an open set, e.g. `reddit`, `news`, `reviews`), or `classifying` while unknown."}},"additionalProperties":false,"type":"object","required":["id","url","created_at"],"title":"TrackedPage","description":"A page the brand follows, with what the answers did with it under the filters; zeros when none cited it."},"TrackedPageCreated":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/TrackedPage"},"type":"array","title":"Data"}},"additionalProperties":false,"type":"object","required":["data"],"title":"TrackedPageCreated","description":"The pages followed; a page already followed comes back as it is."},"TrackedPageList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/TrackedPage"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"True when more items exist past this page. Fetch them with a larger `offset`."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of items matching the query, across all pages."},"limit":{"type":"integer","minimum":1.0,"title":"Limit","description":"Page size that was applied."},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of items skipped before this page."},"total_citations":{"type":"integer","minimum":0.0,"title":"Total Citations","description":"Citations of every matching page under the filters."},"not_cited":{"type":"integer","minimum":0.0,"title":"Not Cited","description":"Matching pages no answer cited under the filters."}},"additionalProperties":false,"type":"object","required":["data","has_more","total","limit","offset","total_citations","not_cited"],"title":"TrackedPageList","description":"A page of tracked pages, cited ones first."},"TrendLocation":{"properties":{"key":{"type":"string","title":"Key"},"region_config_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Region Config Id"},"scheduled_report_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scheduled Report Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country"},"location":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location"}},"additionalProperties":false,"type":"object","required":["key"],"title":"TrendLocation","description":"One place the scope ran in: a schedule's region config, or a one-off run's country and city."},"TrendPrompt":{"properties":{"object":{"type":"string","const":"trend_prompt","title":"Object","description":"Always `trend_prompt`.","default":"trend_prompt"},"key":{"type":"string","title":"Key","description":"The prompt's key, for `prompt_key`."},"region_config_prompt_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Region Config Prompt Id","description":"A schedule's prompt; null for a one-off."},"location_key":{"type":"string","title":"Location Key","description":"The place it ran in, a `locations[].key`, for `location_key`."},"scheduled_report_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scheduled Report Id"},"prompt_text":{"type":"string","title":"Prompt Text"},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category"},"intent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Intent","description":"The prompt's funnel intent: `awareness` (learning about a topic), `consideration` (weighing options) or `decision` (choosing between named options); `null` when unclassified. Written with generated prompts, set by hand otherwise. An open set."},"run_count":{"type":"integer","minimum":0.0,"title":"Run Count","description":"Runs that answered it."},"avg_visibility_pct":{"type":"number","title":"Avg Visibility Pct","description":"Answers naming the brand over all its answers, in percent."},"latest_visibility_pct":{"type":"number","title":"Latest Visibility Pct","description":"The same in its latest run."},"latest_rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Latest Rank","description":"The brand's best position in its latest run."},"trend":{"type":"string","enum":["up","down","stable"],"title":"Trend","description":"`up` or `down` when the newer half of its runs moved more than five points, else `stable`."},"trend_delta":{"type":"number","title":"Trend Delta","description":"The newer half of its runs minus the older half, in points."},"sparkline":{"items":{"type":"number"},"type":"array","title":"Sparkline","description":"Its visibility in each run, oldest first, in percent."}},"additionalProperties":false,"type":"object","required":["key","location_key","prompt_text","run_count","avg_visibility_pct","latest_visibility_pct","trend","trend_delta","sparkline"],"title":"TrendPrompt","description":"One prompt over its runs, oldest first."},"TrendRun":{"properties":{"key":{"type":"string","title":"Key"},"at":{"type":"string","format":"date-time","title":"At"},"report_ids":{"items":{"type":"string"},"type":"array","title":"Report Ids"},"scheduled_report_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scheduled Report Id"}},"additionalProperties":false,"type":"object","required":["key","at","report_ids"],"title":"TrendRun","description":"One run in the scope: its batch (else its report), when it started, its reports and its schedule."},"UndatedArticle":{"properties":{"object":{"type":"string","const":"undated_article","title":"Object","description":"Always `undated_article`.","default":"undated_article"},"id":{"type":"string","title":"Id","description":"Content brief id."},"brand_id":{"type":"string","title":"Brand Id","description":"The brand the article belongs to."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"topic":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Topic"},"content_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content Type"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status","description":"`draft` or `needs_review`."},"generated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Generated At","description":"When it was written, if it was."},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Updated At","description":"When it last changed."},"task_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task Id","description":"The article's board task, when it has one."},"task_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task Status","description":"The board task's status."},"review_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Review Status","description":"The client review's status, when shared."},"approved":{"type":"boolean","title":"Approved","description":"True when the task is `approved` or the client approved it.","default":false}},"additionalProperties":false,"type":"object","required":["id","brand_id"],"title":"UndatedArticle","description":"An article with no day on the calendar: a draft or a ready article with no plan date and nothing queued."},"UndatedArticleList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/UndatedArticle"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"True when more items exist past this page. Fetch them with a larger `offset`."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of items matching the query, across all pages."},"limit":{"type":"integer","minimum":1.0,"title":"Limit","description":"Page size that was applied."},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of items skipped before this page."},"ready":{"type":"integer","minimum":0.0,"title":"Ready","description":"How many of all the undated articles are `needs_review`.","default":0}},"additionalProperties":false,"type":"object","required":["data","has_more","total","limit","offset"],"title":"UndatedArticleList","description":"A page of the articles waiting without a date, newest change first."},"UpdateBrandRequest":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":150,"minLength":1},{"type":"null"}],"title":"Name"},"website":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Website","description":"Primary brand website URL."},"language":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"title":"Language"},"country":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Country"},"brand_aliases":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":50},{"type":"null"}],"title":"Brand Aliases","description":"Replaces the whole list of alternate names. Names that differ only in case or spacing are kept once, with the first spelling sent."},"categories":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":30},{"type":"null"}],"title":"Categories","description":"Free-form industry/topic tags (e.g. `running shoes`, `saas`). Up to 30 entries, each up to 100 characters. Defaults to `[]` on create."},"is_local_business":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Local Business","description":"Whether the brand is a local business. Overrides what brand research found."},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":50},{"type":"null"}],"title":"Tags","description":"Tags that organise your brands, on any plan. Replaces the whole list."},"client_email":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Client Email","description":"Agency client-contact email for the brand, used when delivering reports. Changing a client-contact field needs the brand owner on Agency; below it the request fails with `brand_plan_required`."},"client_name":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Client Name","description":"Agency client-contact name for the brand."},"client_company":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Client Company","description":"Agency client-contact company for the brand."}},"additionalProperties":false,"type":"object","title":"UpdateBrandRequest","description":"Partial-update body for ``PATCH /v1/brands/{brand_id}``.","example":{"categories":["running shoes","trail running"],"name":"adidas Running"}},"UrlInspection":{"properties":{"object":{"type":"string","const":"url_inspection","title":"Object","default":"url_inspection"},"connected":{"type":"boolean","title":"Connected","description":"True when a Search Console site is connected and readable.","default":false},"site_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Site Url","description":"Connected Search Console site the page was inspected on."},"result":{"anyOf":[{"$ref":"#/components/schemas/UrlInspectionResult"},{"type":"null"}],"description":"Inspection result, or `null` when not connected or the page could not be inspected."}},"additionalProperties":false,"type":"object","title":"UrlInspection","description":"Live URL-inspection status for a page on the brand's connected GSC site.","example":{"connected":true,"object":"url_inspection","result":{"coverage_state":"Submitted and indexed","crawled_as":"MOBILE","google_canonical":"https://rankprompt.com/pricing","indexing_state":"INDEXING_ALLOWED","inspection_link":"https://search.google.com/search-console/inspect?...","last_crawl_time":"2026-06-20T11:22:00Z","page_fetch_state":"SUCCESSFUL","referring_urls_count":4,"rich_results":[{"issues":0,"items":1,"type":"Product"}],"rich_results_verdict":"PASS","robots_txt_state":"ALLOWED","sitemaps":["https://rankprompt.com/sitemap.xml"],"user_canonical":"https://rankprompt.com/pricing","verdict":"PASS"},"site_url":"sc-domain:rankprompt.com"}},"UrlInspectionResult":{"properties":{"inspection_link":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Inspection Link","description":"Deep link to the report in Search Console."},"verdict":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Verdict","description":"Overall index verdict (e.g. `PASS`, `FAIL`, `NEUTRAL`)."},"coverage_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Coverage State","description":"Human-readable coverage state."},"robots_txt_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Robots Txt State","description":"robots.txt state (e.g. `ALLOWED`, `DISALLOWED`)."},"indexing_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Indexing State","description":"Indexing state (e.g. `INDEXING_ALLOWED`)."},"page_fetch_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Page Fetch State","description":"Last fetch state (e.g. `SUCCESSFUL`)."},"last_crawl_time":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Last Crawl Time","description":"When Google last crawled the page."},"crawled_as":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Crawled As","description":"Crawl user agent (`MOBILE` or `DESKTOP`)."},"google_canonical":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Google Canonical","description":"Canonical URL Google selected."},"user_canonical":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Canonical","description":"Canonical URL declared by the page."},"referring_urls_count":{"type":"integer","minimum":0.0,"title":"Referring Urls Count","description":"Number of referring URLs Google reports.","default":0},"sitemaps":{"items":{"type":"string"},"type":"array","title":"Sitemaps","description":"Sitemaps that reference the inspected URL."},"rich_results_verdict":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rich Results Verdict","description":"Rich-results verdict, when detected."},"rich_results":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Rich Results","description":"Detected rich-result blocks (raw Google shape)."}},"additionalProperties":false,"type":"object","title":"UrlInspectionResult","description":"Compact result of the Search Console URL Inspection API for a single page."},"UsageByDay":{"properties":{"day":{"type":"string","title":"Day","description":"UTC day (`YYYY-MM-DD`)."},"count":{"type":"integer","minimum":0.0,"title":"Count","description":"Total requests on this day."},"errors":{"type":"integer","minimum":0.0,"title":"Errors","description":"Requests with status >= 400."},"units":{"type":"integer","minimum":0.0,"title":"Units","description":"Request units consumed."},"credits":{"type":"integer","minimum":0.0,"title":"Credits","description":"Credits charged for AI work."}},"additionalProperties":false,"type":"object","required":["day","count","errors","units","credits"],"title":"UsageByDay","description":"Per-day rollup row inside ``GET /v1/me/usage``.","example":{"count":142,"credits":5,"day":"2026-04-19","errors":3,"units":287}},"UsageByEndpoint":{"properties":{"endpoint":{"type":"string","title":"Endpoint","description":"Normalized path (e.g. `/v1/brands/{brand_id}`)."},"method":{"type":"string","title":"Method","description":"HTTP verb."},"count":{"type":"integer","minimum":0.0,"title":"Count","description":"Total requests to this endpoint+method."},"errors":{"type":"integer","minimum":0.0,"title":"Errors","description":"Requests with status >= 400."},"units":{"type":"integer","minimum":0.0,"title":"Units","description":"Request units consumed."},"credits":{"type":"integer","minimum":0.0,"title":"Credits","description":"Credits charged for AI work."}},"additionalProperties":false,"type":"object","required":["endpoint","method","count","errors","units","credits"],"title":"UsageByEndpoint","description":"Per-endpoint rollup row inside ``GET /v1/me/usage``.","example":{"count":84,"credits":0,"endpoint":"/v1/brands/{brand_id}/reports","errors":0,"method":"GET","units":84}},"UsageResponse":{"properties":{"from":{"type":"string","format":"date-time","title":"From","description":"Inclusive window start (UTC, ISO-8601)."},"to":{"type":"string","format":"date-time","title":"To","description":"Exclusive window end (UTC, ISO-8601)."},"account_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Account Id","description":"The account the counts are limited to, when `account_id` was passed; null when they cover every call."},"total_requests":{"type":"integer","minimum":0.0,"title":"Total Requests","description":"Total request count in the window."},"total_errors":{"type":"integer","minimum":0.0,"title":"Total Errors","description":"Requests with status >= 400."},"total_units":{"type":"integer","minimum":0.0,"title":"Total Units","description":"Total request units consumed."},"total_credits":{"type":"integer","minimum":0.0,"title":"Total Credits","description":"Total credits charged for AI work."},"by_day":{"items":{"$ref":"#/components/schemas/UsageByDay"},"type":"array","title":"By Day","description":"Per-day rollup, ascending by day."},"by_endpoint":{"items":{"$ref":"#/components/schemas/UsageByEndpoint"},"type":"array","title":"By Endpoint","description":"Top 50 endpoints by request count."}},"additionalProperties":false,"type":"object","required":["from","to","total_requests","total_errors","total_units","total_credits"],"title":"UsageResponse","description":"Historical RU usage envelope for ``GET /v1/me/usage``.","example":{"by_day":[{"count":142,"credits":5,"day":"2026-04-19","errors":3,"units":287}],"by_endpoint":[{"count":84,"credits":0,"endpoint":"/v1/brands/{brand_id}/reports","errors":0,"method":"GET","units":84}],"from":"2026-04-01T00:00:00+00:00","to":"2026-04-21T00:00:00+00:00","total_credits":47,"total_errors":12,"total_requests":1240,"total_units":2480}},"VideoGap":{"properties":{"prompt":{"type":"string","title":"Prompt"},"answers_without_brand":{"type":"integer","title":"Answers Without Brand"},"videos":{"type":"integer","title":"Videos","description":"Other channels' videos its answers cited.","default":0},"platforms":{"items":{"type":"string"},"type":"array","title":"Platforms","description":"The AI platforms whose answers cited them."}},"additionalProperties":false,"type":"object","required":["prompt","answers_without_brand"],"title":"VideoGap"},"VideoGapPage":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/VideoGap"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"True when more items exist past this page. Fetch them with a larger `offset`."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of items matching the query, across all pages."},"limit":{"type":"integer","minimum":1.0,"title":"Limit","description":"Page size that was applied."},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of items skipped before this page."}},"additionalProperties":false,"type":"object","required":["data","has_more","total","limit","offset"],"title":"VideoGapPage","description":"One page of the prompts to answer in a video, with how many there are in all."},"VisibilityBand":{"properties":{"low":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Low","description":"Lower edge of the 95% band around this run's `visibility_score`, in score points."},"high":{"type":"number","maximum":100.0,"minimum":0.0,"title":"High","description":"Upper edge of the 95% band around this run's `visibility_score`, in score points."},"answers":{"type":"integer","minimum":0.0,"title":"Answers","description":"Answers the score is made of (prompts times AI platforms that answered)."},"runs":{"type":"integer","minimum":0.0,"title":"Runs","description":"Runs of the same prompts (the same schedule location) that widened the band to their own spread; `0` when the band is the binomial floor of this run alone, which is the case under 4 runs."},"previous_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Previous Score","description":"Score of the previous run of the same schedule location, counted only over the answers both runs asked (the same prompt on the same AI platform, in the same country, location and language). `null` for the first run and when the two runs share no answers."},"delta":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Delta","description":"`shared_score` minus `previous_score`: the change over the shared answers, never one made by prompts added or removed. `null` when nothing is compared."},"movement":{"anyOf":[{"type":"string","enum":["up","down","steady"]},{"type":"null"}],"title":"Movement","description":"`steady` when `previous_score` sits inside the noise band of `shared_score` (the change is within normal variation), otherwise the way the score went. That band is `low` to `high` when `shared_answers` equals `answers`; when the runs asked different answers it is the band of the shared ones, which this object does not carry, so `previous_score` can sit inside `low` to `high` and still move. `null` when nothing is compared."},"shared_answers":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Shared Answers","description":"Answers both runs asked, the only ones `previous_score`, `shared_score` and `delta` count. Equal to `answers` when both runs asked the same prompts on the same AI platforms; `0` when they share none; `null` for the first run."},"shared_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Shared Score","description":"This run's score over the shared answers. The same as `visibility_score` when both runs asked the same answers. `null` when nothing is compared."},"new_prompts":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"New Prompts","description":"Prompts this run asked that the previous run did not. They count in `visibility_score` and never in `delta`. `null` for the first run."}},"additionalProperties":false,"type":"object","required":["low","high","answers","runs"],"title":"VisibilityBand","description":"The noise band of a score: where a rerun of the same prompts would plausibly land."},"VisibilitySlice":{"properties":{"key":{"type":"string","title":"Key","description":"The engine id (e.g. `chatgpt`) or the prompt category."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Answers in this slice."},"ranked":{"type":"integer","minimum":0.0,"title":"Ranked","description":"Answers that mentioned the brand."},"visibility_score":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Visibility Score","description":"`ranked` over `total`, as a percentage."}},"additionalProperties":false,"type":"object","required":["key","total","ranked","visibility_score"],"title":"VisibilitySlice","description":"How often the brand appeared in one slice of a report's answers."},"VisibilityTrends":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/TrendPrompt"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","description":"True when more items exist past this page. Fetch them with a larger `offset`."},"total":{"type":"integer","minimum":0.0,"title":"Total","description":"Total number of items matching the query, across all pages."},"limit":{"type":"integer","minimum":1.0,"title":"Limit","description":"Page size that was applied."},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of items skipped before this page."},"engines":{"items":{"type":"string"},"type":"array","title":"Engines","description":"AI platforms the runs asked (an open set)."},"runs":{"items":{"$ref":"#/components/schemas/TrendRun"},"type":"array","title":"Runs","description":"Every run of the scope, oldest first."},"locations":{"items":{"$ref":"#/components/schemas/TrendLocation"},"type":"array","title":"Locations"},"total_runs":{"type":"integer","minimum":0.0,"title":"Total Runs","default":0},"run_changes":{"items":{"$ref":"#/components/schemas/RunChange"},"type":"array","title":"Run Changes","description":"Runs that asked other prompts, engines or places than their schedule's run before."},"competitor_race":{"anyOf":[{"$ref":"#/components/schemas/CompetitorRace"},{"type":"null"}],"description":"With `competitors=true`: the competitors named most over the runs."}},"additionalProperties":false,"type":"object","required":["data","has_more","total","limit","offset"],"title":"VisibilityTrends","description":"The runs, places and engines of the scope, a page of its prompts, the run changes and the competitor race."},"VoiceProfile":{"properties":{"persona":{"type":"string","title":"Persona","description":"Who is speaking and to whom, in one sentence.","default":""},"sentence_length":{"anyOf":[{"type":"string","enum":["short","medium","long"]},{"type":"null"}],"title":"Sentence Length"},"reading_level":{"anyOf":[{"type":"string","enum":["plain","professional","expert"]},{"type":"null"}],"title":"Reading Level"},"formatting_habits":{"items":{"type":"string"},"type":"array","title":"Formatting Habits","description":"Habits such as lists for steps."},"recurring_phrases":{"items":{"type":"string"},"type":"array","title":"Recurring Phrases","description":"Phrases the brand repeats, as written."},"words_to_avoid":{"items":{"type":"string"},"type":"array","title":"Words To Avoid","description":"Words that would sound off in this voice; candidates for `banned_phrases`."},"writing_style":{"type":"string","title":"Writing Style","description":"Instructions a writer can follow; a candidate for `writing_style`.","default":""},"sources":{"items":{"type":"string"},"type":"array","title":"Sources","description":"The pages it was learned from."}},"additionalProperties":false,"type":"object","title":"VoiceProfile","description":"How the brand's own posts read, learned from its site. A proposal: nothing in it is applied until you copy\nit into the preferences."},"Webhook":{"properties":{"object":{"type":"string","title":"Object","description":"Always `webhook`.","default":"webhook"},"id":{"type":"string","title":"Id","description":"Endpoint id (`whk_…`)."},"brand_id":{"type":"string","title":"Brand Id","description":"Owning brand id (UUID)."},"url":{"type":"string","title":"Url","description":"HTTPS URL deliveries are POSTed to."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Caller-facing label."},"events":{"items":{"type":"string","enum":["report.completed","report.failed","schedule.run.completed","schedule.run.failed","local_rank.dropped","article.published","article.updated","article.unpublished"]},"type":"array","title":"Events","description":"The events this endpoint receives: reports, scheduled runs, a scheduled map scan's local rank drops, and articles going live, updated or taken down. The set is open: a new event type can appear."},"destination_type":{"type":"string","enum":["generic","slack","discord"],"title":"Destination Type","description":"How deliveries are formatted: `generic`, `slack` or `discord`.","default":"generic"},"is_active":{"type":"boolean","title":"Is Active","description":"Whether deliveries are dispatched."},"secret_fingerprint":{"type":"string","title":"Secret Fingerprint","description":"Masked signing secret, safe to display."},"secret_version":{"type":"integer","title":"Secret Version","description":"Bumps on each secret rotation."},"consecutive_failures":{"type":"integer","title":"Consecutive Failures","description":"Failed deliveries in a row; resets on success."},"disabled_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Disabled Reason","description":"Why the endpoint was disabled, if it is."},"last_success_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Last Success At","description":"Last successful delivery time."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"ISO-8601 creation time."}},"additionalProperties":false,"type":"object","required":["id","brand_id","url","events","is_active","secret_fingerprint","secret_version","consecutive_failures","created_at"],"title":"Webhook","description":"A webhook endpoint (never carries the signing secret)."},"WebhookCreate":{"properties":{"destination_type":{"type":"string","enum":["generic","slack","discord"],"title":"Destination Type","description":"`generic` posts the signed JSON envelope. `slack` and `discord` post a readable message to an incoming webhook URL of that platform (the host is checked) and still carry the signature header.","default":"generic"},"url":{"type":"string","maxLength":2048,"title":"Url","description":"HTTPS endpoint URL."},"events":{"items":{"type":"string","enum":["report.completed","report.failed","schedule.run.completed","schedule.run.failed","local_rank.dropped","article.published","article.updated","article.unpublished"]},"type":"array","maxItems":10,"minItems":1,"title":"Events","description":"One or more event types to subscribe to."},"description":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Description","description":"Your own label for this endpoint. Not sent to the destination."}},"additionalProperties":false,"type":"object","required":["url","events"],"title":"WebhookCreate","description":"Body for ``POST /v1/brands/{brand_id}/webhooks``."},"WebhookDelivery":{"properties":{"object":{"type":"string","title":"Object","default":"webhook.delivery"},"id":{"type":"string","title":"Id"},"endpoint_id":{"type":"string","title":"Endpoint Id"},"event_type":{"type":"string","title":"Event Type"},"event_id":{"type":"string","title":"Event Id"},"status":{"type":"string","enum":["pending","dispatching","delivered","dropped"],"title":"Status"},"attempt":{"type":"integer","title":"Attempt"},"response_status":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Response Status"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"},"is_test":{"type":"boolean","title":"Is Test","description":"True for a test delivery sent from the dashboard or the API.","default":false},"duration_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Duration Ms","description":"Round trip of the attempt in milliseconds, when timed."},"scheduled_at":{"type":"string","format":"date-time","title":"Scheduled At"},"delivered_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Delivered At"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"additionalProperties":false,"type":"object","required":["id","endpoint_id","event_type","event_id","status","attempt","scheduled_at","created_at"],"title":"WebhookDelivery","description":"A single dispatch attempt record (debug aid)."},"WebhookDeliveryList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/WebhookDelivery"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Opaque continuation token. Pass back as `?cursor=` to fetch the next page. `null` when `has_more` is false."}},"additionalProperties":false,"type":"object","required":["data","has_more"],"title":"WebhookDeliveryList","description":"Cursor-paginated list of deliveries."},"WebhookDeliveryReplayed":{"properties":{"object":{"type":"string","title":"Object","default":"webhook.delivery_replay"},"delivery_id":{"type":"string","title":"Delivery Id","description":"Id of the newly enqueued delivery."},"status":{"type":"string","enum":["pending","dispatching","delivered","dropped"],"title":"Status"}},"additionalProperties":false,"type":"object","required":["delivery_id","status"],"title":"WebhookDeliveryReplayed","description":"Response for ``POST .../deliveries/{id}/replays``."},"WebhookList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/Webhook"},"type":"array","title":"Data"}},"additionalProperties":false,"type":"object","required":["data"],"title":"WebhookList","description":"List of a brand's webhook endpoints, unpaginated and ordered newest-first."},"WebhookSecretRotated":{"properties":{"object":{"type":"string","title":"Object","default":"webhook.secret_rotation"},"id":{"type":"string","title":"Id","description":"Endpoint id."},"secret":{"type":"string","title":"Secret","description":"New signing secret (plaintext). The old secret stays valid for 24h."},"secret_version":{"type":"integer","title":"Secret Version","description":"Incremented version."}},"additionalProperties":false,"type":"object","required":["id","secret","secret_version"],"title":"WebhookSecretRotated","description":"Response for ``POST .../secret-rotations``: the new plaintext secret, once."},"WebhookTestDelivery":{"properties":{"object":{"type":"string","title":"Object","description":"Always `webhook.test_delivery`.","default":"webhook.test_delivery"},"delivery_id":{"type":"string","title":"Delivery Id","description":"Id of the delivery row, listed with `is_test: true` in `GET .../deliveries`."},"event_id":{"type":"string","title":"Event Id","description":"Id of the sample event, starting with `evt_test_`."},"event_type":{"type":"string","title":"Event Type","description":"The event type the sample was sent as."},"status":{"type":"string","enum":["delivered","failed"],"title":"Status","description":"`delivered` when the endpoint answered 2xx; `failed` for any other answer (see `response_status`) or none at all (see `error`)."},"response_status":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Response Status","description":"HTTP status the endpoint answered; null when it never answered."},"duration_ms":{"type":"integer","title":"Duration Ms","description":"Round trip of the request in milliseconds."},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Why the delivery failed: `HTTP <status>`, a timeout, a connection error or a host that is not public; null when delivered."}},"additionalProperties":false,"type":"object","required":["delivery_id","event_id","event_type","status","duration_ms"],"title":"WebhookTestDelivery","description":"What the endpoint answered to a test delivery, sent at once rather than queued."},"CreateWebhookTestDeliveryRequest":{"properties":{"event":{"type":"string","maxLength":100,"minLength":1,"title":"Event","description":"An event type the endpoint subscribes to. The sample carries `test: true` and an `evt_test_` id."}},"additionalProperties":false,"type":"object","required":["event"],"title":"CreateWebhookTestDeliveryRequest","description":"Body for ``POST /v1/brands/{brand_id}/webhooks/{id}/test-deliveries``."},"WebhookUpdate":{"properties":{"destination_type":{"anyOf":[{"type":"string","enum":["generic","slack","discord"]},{"type":"null"}],"title":"Destination Type","description":"Change how deliveries are formatted; the URL must match the new type's host."},"url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Url","description":"New https destination. Rotating the URL does not rotate the signing secret."},"events":{"anyOf":[{"items":{"type":"string","enum":["report.completed","report.failed","schedule.run.completed","schedule.run.failed","local_rank.dropped","article.published","article.updated","article.unpublished"]},"type":"array","maxItems":10,"minItems":1},{"type":"null"}],"title":"Events","description":"Replaces the whole subscription list; send every event you still want."},"description":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Description","description":"Your own label for this endpoint. Not sent to the destination."},"is_active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Active","description":"Set `true` to re-enable a disabled endpoint."}},"additionalProperties":false,"type":"object","title":"WebhookUpdate","description":"Partial-update body for ``PATCH /v1/brands/{brand_id}/webhooks/{id}``."},"WebhookWithSecret":{"properties":{"object":{"type":"string","title":"Object","description":"Always `webhook`.","default":"webhook"},"id":{"type":"string","title":"Id","description":"Endpoint id (`whk_…`)."},"brand_id":{"type":"string","title":"Brand Id","description":"Owning brand id (UUID)."},"url":{"type":"string","title":"Url","description":"HTTPS URL deliveries are POSTed to."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Caller-facing label."},"events":{"items":{"type":"string","enum":["report.completed","report.failed","schedule.run.completed","schedule.run.failed","local_rank.dropped","article.published","article.updated","article.unpublished"]},"type":"array","title":"Events","description":"The events this endpoint receives: reports, scheduled runs, a scheduled map scan's local rank drops, and articles going live, updated or taken down. The set is open: a new event type can appear."},"destination_type":{"type":"string","enum":["generic","slack","discord"],"title":"Destination Type","description":"How deliveries are formatted: `generic`, `slack` or `discord`.","default":"generic"},"is_active":{"type":"boolean","title":"Is Active","description":"Whether deliveries are dispatched."},"secret_fingerprint":{"type":"string","title":"Secret Fingerprint","description":"Masked signing secret, safe to display."},"secret_version":{"type":"integer","title":"Secret Version","description":"Bumps on each secret rotation."},"consecutive_failures":{"type":"integer","title":"Consecutive Failures","description":"Failed deliveries in a row; resets on success."},"disabled_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Disabled Reason","description":"Why the endpoint was disabled, if it is."},"last_success_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Last Success At","description":"Last successful delivery time."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"ISO-8601 creation time."},"secret":{"type":"string","title":"Secret","description":"Signing secret (plaintext). Shown once; store it now."}},"additionalProperties":false,"type":"object","required":["id","brand_id","url","events","is_active","secret_fingerprint","secret_version","consecutive_failures","created_at","secret"],"title":"WebhookWithSecret","description":"Create response: includes the plaintext signing secret, returned exactly once."},"WebsiteAutopilot":{"properties":{"object":{"type":"string","const":"website_autopilot","title":"Object","default":"website_autopilot"},"enabled":{"type":"boolean","title":"Enabled"},"configured":{"type":"boolean","title":"Configured","description":"False before it was ever turned on."},"autonomy":{"anyOf":[{"type":"string","enum":["none","some","all"]},{"type":"null"}],"title":"Autonomy"},"scan_weekday":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Scan Weekday","description":"0 Monday to 6 Sunday, in the owner's time zone."},"next_scan_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Next Scan At"},"scan":{"anyOf":[{"$ref":"#/components/schemas/WebsiteAutopilotScan"},{"type":"null"}],"description":"The newest scan, running or ended."},"pages_read":{"type":"integer","title":"Pages Read","description":"Pages the last finished scan checked."},"checks_failing":{"type":"integer","title":"Checks Failing","description":"Failing checks the last finished scan found."},"decisions":{"$ref":"#/components/schemas/WebsiteAutopilotDecisions"},"writing":{"type":"integer","title":"Writing","description":"Pages whose proposal is being written."},"stopped":{"$ref":"#/components/schemas/WebsiteAutopilotStopped"},"live":{"$ref":"#/components/schemas/WebsiteAutopilotLive"},"cities_without_page":{"$ref":"#/components/schemas/WebsiteAutopilotCities"}},"additionalProperties":false,"type":"object","required":["enabled","configured","pages_read","checks_failing","decisions","writing","stopped","live","cities_without_page"],"title":"WebsiteAutopilot","description":"Website autopilot of a brand for its owner."},"WebsiteAutopilotCities":{"properties":{"total":{"type":"integer","title":"Total"},"names":{"items":{"type":"string"},"type":"array","title":"Names","description":"The first ten."}},"additionalProperties":false,"type":"object","required":["total"],"title":"WebsiteAutopilotCities"},"WebsiteAutopilotDecisionPage":{"properties":{"key":{"type":"string","title":"Key"},"kind":{"type":"string","enum":["existing","new"],"title":"Kind"},"url":{"type":"string","title":"Url"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"changes":{"type":"integer","title":"Changes","description":"Changes on it not decided yet, each written on every language version of the page.","default":0},"credits":{"type":"number","title":"Credits","description":"Credits its proposals reserved when they were written.","default":0}},"additionalProperties":false,"type":"object","required":["key","kind","url"],"title":"WebsiteAutopilotDecisionPage"},"WebsiteAutopilotDecisions":{"properties":{"total":{"type":"integer","title":"Total","description":"Pages whose proposed changes wait on the owner's review."},"new":{"type":"integer","title":"New","description":"Of them, pages to create."},"existing":{"type":"integer","title":"Existing","description":"Of them, pages of the site."},"changes":{"type":"integer","title":"Changes","description":"Changes those pages hold that are not decided yet, as the owner reviews them: one per change, which is written on every language version of its page."},"versions":{"type":"integer","title":"Versions","description":"Those changes counted once per language version they write; the same as `changes` on a site in one language.","default":0},"questions":{"type":"integer","title":"Questions","description":"Questions on those pages only the owner can answer."},"credits":{"type":"number","title":"Credits","description":"Credits the proposals of those pages reserved when they were written.","default":0},"pages":{"items":{"$ref":"#/components/schemas/WebsiteAutopilotDecisionPage"},"type":"array","title":"Pages","description":"The first few, most pressing first."}},"additionalProperties":false,"type":"object","required":["total","new","existing","changes","questions"],"title":"WebsiteAutopilotDecisions"},"WebsiteAutopilotLive":{"properties":{"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"items":{"items":{"$ref":"#/components/schemas/WebsiteAutopilotLivePage"},"type":"array","title":"Items"}},"additionalProperties":false,"type":"object","required":["total","limit","offset"],"title":"WebsiteAutopilotLive"},"WebsiteAutopilotLivePage":{"properties":{"key":{"type":"string","title":"Key"},"kind":{"type":"string","enum":["existing","new"],"title":"Kind"},"url":{"type":"string","title":"Url"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"status":{"type":"string","enum":["live","indexed"],"title":"Status"}},"additionalProperties":false,"type":"object","required":["key","kind","url","status"],"title":"WebsiteAutopilotLivePage"},"WebsiteAutopilotScan":{"properties":{"trigger":{"type":"string","enum":["weekly","manual","first","api"],"title":"Trigger"},"status":{"type":"string","enum":["queued","running","done","partial","failed","skipped"],"title":"Status","description":"`queued` or `running` while it reads the site."},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"Why a scan ended `partial`, `failed` or `skipped`."},"queued_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Queued At"},"started_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Started At"},"finished_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Finished At"},"phase":{"anyOf":[{"type":"string","enum":["listing","reading","analyzing","checks","new_pages"]},{"type":"null"}],"title":"Phase","description":"The step a running scan is on."},"pages_read":{"type":"integer","title":"Pages Read","description":"Pages a running scan read of `pages_total`.","default":0},"pages_total":{"type":"integer","title":"Pages Total","default":0}},"additionalProperties":false,"type":"object","required":["trigger","status"],"title":"WebsiteAutopilotScan"},"WebsiteAutopilotStopped":{"properties":{"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"items":{"items":{"$ref":"#/components/schemas/WebsiteAutopilotStoppedPage"},"type":"array","title":"Items"}},"additionalProperties":false,"type":"object","required":["total","limit","offset"],"title":"WebsiteAutopilotStopped"},"WebsiteAutopilotStoppedPage":{"properties":{"key":{"type":"string","title":"Key"},"kind":{"type":"string","enum":["existing","new"],"title":"Kind"},"url":{"type":"string","title":"Url"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"step":{"type":"string","enum":["written","approved","on_site","seen","result"],"title":"Step","description":"The step of written, approved, on_site, seen, result it stopped at."},"reason":{"type":"string","enum":["needs_answers","waiting_on_owner_task","needs_publish","not_answering","no_item_page","conflict","failed","paused"],"title":"Reason","description":"Why it cannot take its next step without the owner."},"provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider","description":"The platform the owner acts in, when one."},"paused_reason":{"anyOf":[{"type":"string","enum":["plan","disconnected","destination_error","control","held","scan","article","new_page","proposal"]},{"type":"null"}],"title":"Paused Reason","description":"Why a `paused` page is held."}},"additionalProperties":false,"type":"object","required":["key","kind","url","step","reason"],"title":"WebsiteAutopilotStoppedPage"},"WordPressCredentials":{"properties":{"site_url":{"type":"string","maxLength":2000,"minLength":1,"title":"Site Url","description":"Base URL of the WordPress site, for example `https://rankprompt.com`. Must be `https`, since the application password is sent on every publish. Hosts that resolve to private, loopback or link-local addresses are rejected."},"username":{"type":"string","maxLength":200,"minLength":1,"title":"Username","description":"WordPress username the application password belongs to."},"application_password":{"type":"string","maxLength":200,"minLength":1,"title":"Application Password","description":"A WordPress application password (Users, then Profile, then Application Passwords), not the account password. Stored encrypted and never returned by this API."}},"additionalProperties":false,"type":"object","required":["site_url","username","application_password"],"title":"WordPressCredentials","description":"WordPress site plus an application password to publish with."},"YouTubeChannel":{"properties":{"object":{"type":"string","const":"youtube_channel","title":"Object","default":"youtube_channel"},"connected":{"type":"boolean","title":"Connected","description":"The brand has a live Google connection."},"expired":{"type":"boolean","title":"Expired","description":"The brand's Google connection lapsed: it is reconnected in the app.","default":false},"granted":{"type":"boolean","title":"Granted","description":"The connection's grant covers YouTube (youtube.readonly)."},"channel_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Channel Id"},"channel_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Channel Title"},"synced_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Synced At","description":"When the uploads were last read from YouTube."},"videos":{"items":{"$ref":"#/components/schemas/OwnVideo"},"type":"array","title":"Videos","description":"Every upload of the channel, newest first."},"private_videos":{"type":"integer","minimum":0.0,"title":"Private Videos","description":"Uploads the last read skipped for being private or unlisted; with no public upload, why `videos` is empty.","default":0},"cited_videos":{"type":"integer","title":"Cited Videos","description":"YouTube videos the brand's answers cited in the last 90 days."},"own_cited_videos":{"type":"integer","title":"Own Cited Videos"},"other_videos":{"items":{"$ref":"#/components/schemas/CitedVideo"},"type":"array","title":"Other Videos","description":"Other channels' videos cited in answers that left the brand out, most such answers first."},"gaps":{"items":{"$ref":"#/components/schemas/VideoGap"},"type":"array","title":"Gaps","description":"The first ten prompts to answer in a video, most such answers first; the rest page through `GET /v1/brands/{brand_id}/youtube/gaps`."},"gap_count":{"type":"integer","title":"Gap Count","description":"How many prompts to answer in a video there are in all.","default":0},"videos_to_fix":{"type":"integer","title":"Videos To Fix","description":"Public uploads without captions, or without chapters when they are long enough for three."}},"additionalProperties":false,"type":"object","required":["connected","granted","channel_id","channel_title","videos","cited_videos","own_cited_videos","other_videos","gaps","videos_to_fix"],"title":"YouTubeChannel","description":"The brand's own channel, its uploads with what AI cites of them, the videos AI cites without the brand, the gaps."},"YouTubeTasks":{"properties":{"object":{"type":"string","const":"youtube_tasks","title":"Object","default":"youtube_tasks"},"suggested":{"type":"integer","title":"Suggested","description":"Tasks the channel's gaps call for."},"created":{"type":"integer","title":"Created","description":"The new ones; the others already existed and kept their stage."}},"additionalProperties":false,"type":"object","required":["suggested","created"],"title":"YouTubeTasks"},"Body_upload_knowledge_file_v1_brands__brand_id__knowledge_base_files_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File","description":"The document or image."}},"type":"object","required":["file"],"title":"Body_upload_knowledge_file_v1_brands__brand_id__knowledge_base_files_post"},"Citation":{"properties":{"object":{"type":"string","const":"citation","title":"Object","description":"Always `citation`.","default":"citation"},"id":{"type":"string","title":"Id","description":"Citation id (UUID)."},"brand_id":{"type":"string","title":"Brand Id","description":"Owning brand id (UUID)."},"url":{"type":"string","title":"Url","description":"Normalised page URL. Unique per `(brand_id, citation_url)`."},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain","description":"Bare domain extracted from `url` (e.g. `runnersworld.com`)."},"page_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Page Title","description":"`<title>` of the page."},"page_summary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Page Summary","description":"LLM-generated one-paragraph summary of the page."},"image_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Url","description":"The page's preview image (`og:image` or the engine's thumbnail), `null` until the page is read."},"published_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"format":"date-time","title":"Published At","description":"When the page says it was published, `null` when it does not say or was not read yet."},"author":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Author","description":"The person the page names as its author, `null` when it names none or was not read yet."},"site_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Site Name","description":"The site's own name (`og:site_name`, e.g. `The Verge`), `null` when unknown."},"modified_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"format":"date-time","title":"Modified At","description":"When the page says it was last updated (`article:modified_time`, `og:updated_time` or JSON-LD `dateModified`), `null` when it does not say or was not read yet."},"schema_types":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Schema Types","description":"The Schema.org types the page's JSON-LD declares (e.g. `Article`, `FAQPage`, `Product`), sorted, the first 20 when it declares more; `null` when it declares none or was not read yet."},"page_category":{"anyOf":[{"type":"string","enum":["HOMEPAGE","PRODUCT_PAGE","LISTICLE_COMPARISON","REVIEW_ROUNDUP","NEWS_ARTICLE","BLOG_POST","GUIDE_TUTORIAL","DOCUMENTATION","DIRECTORY_LISTING","OTHER"]},{"type":"null"}],"title":"Page Category","description":"Coarse page category. One of `HOMEPAGE`, `PRODUCT_PAGE`, `LISTICLE_COMPARISON`, `REVIEW_ROUNDUP`, `NEWS_ARTICLE`, `BLOG_POST`, `GUIDE_TUTORIAL`, `DOCUMENTATION`, `DIRECTORY_LISTING`, `OTHER`, or `null` while uncategorized."},"site_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Site Type","description":"What the whole site is, an open set (new values can appear): `reddit`, `youtube`, `linkedin`, `wikipedia`, `qa_forum`, `social`, `news`, `reviews`, `reference`, `institutional`, `company`, `marketplace`, `google_place`, `google_product` or `other`; `null` while the site is still being classified."},"relation":{"type":"string","enum":["owned","competitor","none"],"title":"Relation","description":"The page's relation to the brand: `owned` (the brand's own site), `competitor` (the site of an active direct or indirect competitor in the brand's registry) or `none`."},"categorization_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Categorization Status","description":"Categorization state. Pages are categorized automatically a few minutes after the report that cites them, at no cost. `null` = not started yet, `pending` = being categorized, `completed` = categorized, `failed` = not categorized for good (three failed attempts, a URL too long, or an older failure)."},"categorized_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"format":"date-time","title":"Categorized At","description":"When categorization last finished."},"rankprompt_score":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Rankprompt Score","description":"Outreach score, 0-100 (higher is better): how much the engines cite the page (0-40), whether it names the brand's competitors and not the brand (0-25), how reachable the site is (-30 to 20) and how well the page fits (0-15). 0 for the brand's own site, a competitor's site and a page that already links to the brand. Recomputed whenever one of its signals changes."},"analyzed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"format":"date-time","title":"Analyzed At","description":"When a paid Analyze read the page for its contacts, its backlink and the brands it names, or when a user recorded by hand whether the page names the brand. `null` = not analyzed."},"brand_mentioned":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Brand Mentioned","description":"Whether the page names the brand, as read by an Analyze of the page or set by a user. `null` until the page is analyzed: a page that was not read is never reported as not naming the brand."},"brand_mention_sentiment":{"anyOf":[{"type":"string","enum":["positive","neutral","negative"]},{"type":"null"}],"title":"Brand Mention Sentiment","description":"Polarity of the brand mention. One of `positive`, `neutral`, `negative`, or `null` when no mention was found."},"mention_prominence":{"anyOf":[{"type":"string","enum":["headline","body","sidebar","footnote","comparison"]},{"type":"null"}],"title":"Mention Prominence","description":"Where on the page the brand mention appears. One of `headline`, `body`, `sidebar`, `footnote`, `comparison`, or `null` when no mention was found."},"has_backlink":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Backlink","description":"True when the page links back to a brand-owned domain. `false` only once an Analyze or a backlink check read the page; `null` before that."},"backlink_anchor_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Backlink Anchor Text","description":"Anchor text of the backlink, when present."},"backlink_is_nofollow":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Backlink Is Nofollow"},"backlink_is_sponsored":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Backlink Is Sponsored"},"backlink_is_ugc":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Backlink Is Ugc"},"backlink_method":{"anyOf":[{"type":"string","enum":["parser","redirect","llm_candidate"]},{"type":"null"}],"title":"Backlink Method","description":"How the link was established: `parser` (an anchor to the brand in the page's markup), `redirect` (a link that lands on the brand once its redirects are followed), or `llm_candidate` (a model pointed at a link that did not confirm, so `has_backlink` stays `false`). `null` when nothing was found."},"backlink_candidate_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Backlink Candidate Url","description":"The unconfirmed link behind `backlink_method: llm_candidate`; verify it to confirm."},"backlink_status":{"anyOf":[{"type":"string","enum":["live","lost","rel_changed","url_changed","unreachable"]},{"type":"null"}],"title":"Backlink Status","description":"What the weekly re-read of a won backlink found: `live`, `lost` (the link is gone, `has_backlink` turns `false`), `rel_changed` (now nofollow, sponsored or ugc), `url_changed` (points at another page of the brand) or `unreachable` (the page could not be read; nothing changed). `null` until one ran."},"backlink_checked_at":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date-time","title":"Backlink Checked At","description":"When the weekly re-read last read the page."},"is_actionable":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Actionable","description":"True when the page is worth pursuing for outreach."},"chatgpt_count":{"type":"integer","minimum":0.0,"title":"Chatgpt Count","description":"Times this URL was cited by ChatGPT.","default":0},"perplexity_count":{"type":"integer","minimum":0.0,"title":"Perplexity Count","description":"Times this URL was cited by Perplexity for the brand.","default":0},"ai_overviews_count":{"type":"integer","minimum":0.0,"title":"Ai Overviews Count","description":"Times this URL appeared in Google AI Mode (AI Overviews) answers.","default":0},"chatgpt_search_count":{"type":"integer","minimum":0.0,"title":"Chatgpt Search Count","description":"Times this URL was cited by ChatGPT Search, retired from new runs; past answers keep it.","default":0},"claude_count":{"type":"integer","minimum":0.0,"title":"Claude Count","description":"Times this URL was cited by Claude.","default":0},"claude_search_count":{"type":"integer","minimum":0.0,"title":"Claude Search Count","description":"Times this URL was cited by Claude Search, retired from new runs; past answers keep it.","default":0},"gemini_count":{"type":"integer","minimum":0.0,"title":"Gemini Count","description":"Times this URL was cited by Gemini with Google Search grounding.","default":0},"grok_count":{"type":"integer","minimum":0.0,"title":"Grok Count","description":"Times this URL was cited by Grok (xAI Agent Tools web_search).","default":0},"muse_count":{"type":"integer","minimum":0.0,"title":"Muse Count","description":"Times this URL was cited by Muse (Meta Model API web_search), once enabled.","default":0},"report_ids":{"items":{"type":"string"},"type":"array","title":"Report Ids","description":"Report ids (UUIDs) where this citation appeared."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the citation was first ingested."},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"When the citation row was last updated."}},"additionalProperties":false,"type":"object","required":["id","brand_id","url","relation","created_at","updated_at"],"title":"Citation","description":"A tracked URL where the brand may appear.","example":{"ai_overviews_count":0,"analyzed_at":"2026-04-16T09:12:00+00:00","author":"Amanda Furrer","backlink_anchor_text":"adidas Adizero Boston 12","backlink_is_nofollow":false,"backlink_is_sponsored":false,"backlink_is_ugc":false,"backlink_method":"parser","brand_id":"3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04","brand_mention_sentiment":"positive","brand_mentioned":true,"categorization_status":"completed","categorized_at":"2026-04-15T10:30:00+00:00","chatgpt_count":3,"chatgpt_search_count":2,"claude_count":0,"claude_search_count":1,"created_at":"2026-04-15T10:00:00+00:00","domain":"runnersworld.com","gemini_count":1,"grok_count":0,"has_backlink":true,"id":"5b9c7e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f","image_url":"https://hips.hearstapps.com/best-running-shoes.jpg","is_actionable":true,"mention_prominence":"headline","muse_count":0,"object":"citation","page_category":"LISTICLE_COMPARISON","page_summary":"Tested picks of road and trail running shoes for every budget.","page_title":"The Best Running Shoes of 2026","perplexity_count":1,"published_at":"2026-05-14T12:00:00+00:00","rankprompt_score":78,"relation":"none","report_ids":["c4f8b6a2-9a17-4e31-92fa-7d1e3b5c8b2a"],"site_name":"Runner's World","site_type":"news","updated_at":"2026-04-15T10:30:00+00:00","url":"https://www.runnersworld.com/gear/a20865766/best-running-shoes/"}},"ReportCitation":{"properties":{"object":{"type":"string","const":"citation","title":"Object","description":"Always `citation`.","default":"citation"},"url":{"type":"string","title":"Url","description":"Citation URL."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"Page title returned by the provider."},"snippet":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Snippet","description":"Snippet / description returned by the provider."},"cited_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cited Text","description":"Verbatim text quoted from the page (Anthropic-style grounding)."},"published_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Published Date","description":"Publication date in ISO format if known."},"last_updated":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Updated","description":"Last-updated timestamp if known."},"page_age":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Page Age","description":"Page-age string returned by the provider."},"source_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Name","description":"Human-readable source name."},"favicon_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Favicon Url","description":"Favicon / source icon URL."},"thumbnail_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Thumbnail Url","description":"Thumbnail image URL."},"start_index":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Start Index","description":"Zero-based start index of the cited span in the answer text."},"end_index":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"End Index","description":"Zero-based end index of the cited span in the answer text."},"reference_index":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Reference Index","description":"Provider-assigned index that ties text-block reference markers back to this citation."},"google_place_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Google Place Url","description":"For a Google Maps place a Google AI Mode (AI Overviews) answer cites: its Google listing. Once the place is resolved (within a few hours of the report), `url` is the business's own website and the citation counts under that domain; until then `url` is this listing. Null for every other citation."},"google_place":{"anyOf":[{"$ref":"#/components/schemas/GooglePlace"},{"type":"null"}],"description":"For a Google Maps place: what the answer's place card and its Maps listing say about it. Null for every other citation."}},"additionalProperties":false,"type":"object","required":["url"],"title":"ReportCitation","description":"A citation surfaced alongside an AI platform answer.","example":{"object":"citation","snippet":"The adidas Adizero Boston 12 earns high marks as a marathon trainer...","source_name":"Runner's World","title":"The Best Running Shoes of 2026","url":"https://www.runnersworld.com/gear/a20865766/best-running-shoes/"}},"ApiError":{"type":"object","title":"ApiError","description":"Canonical error envelope returned by every `/v1/*` 4xx and 5xx response. The `error.code` field is stable and machine-readable; branch on it instead of the HTTP status. See the [Errors](https://rankprompt.com/docs/v1/errors/) page for the full catalog.","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code from the catalog.","example":"validation_error"},"message":{"type":"string","description":"Human-readable description suitable for logging.","example":"Request validation failed"},"details":{"type":"object","description":"Optional, code-specific context (e.g. `errors` array for `validation_error`, `retry_after` for `service_unavailable`). Shape depends on `error.code`; treat as opaque otherwise.","additionalProperties":true}}},"request_id":{"type":"string","format":"uuid","description":"Server-generated correlation id for the request. Mirrors the `X-Correlation-ID` response header. Include this when contacting support.","example":"9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"}}}},"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"rp_live_*","description":"API key minted from the developer dashboard. A key acts in the account that was active when it was created: its creator's own, or a team account they belong to, with their role there. A team account key stops working with `403 account_membership_required` once its creator leaves that account. Pass as `Authorization: Bearer rp_live_...`. See [Authentication](https://rankprompt.com/docs/v1/authentication/) for details on key formats and scopes."}}},"tags":[{"name":"Account","description":"Inspect the principal behind the current API key, the account it acts in, and the request quota for the active billing period."},{"name":"Brands","description":"Create, read, update and delete brands. Brand-restricted API keys are scoped to a single brand and cannot mint new ones."},{"name":"Brand facts","description":"LLM-researched brand profile (description, industry, value proposition, and more). Generated synchronously via `POST /v1/brands/{id}/facts`; the call may block up to 180s."},{"name":"Reports","description":"Create, list, retrieve and re-run AI visibility reports. Report creation is asynchronous and returns a `job_id` you can poll on `GET /v1/jobs/{id}`."},{"name":"Prompts","description":"Mutate the prompts attached to a report (bulk-create, update, delete), and read every prompt a brand tracks or ran with `GET /v1/brands/{brand_id}/prompts`: one row per prompt text with its runs, visibility and trend, and the engines' answers to them with `GET /v1/brands/{brand_id}/prompts/answers`. A report's prompts also come inline on `GET /v1/reports/{id}` with their per-platform results."},{"name":"Visibility trends","description":"The brand's visibility over its completed runs, one-off reports and schedules alike: each prompt per run with its trend, the runs whose ask changed, and the competitors named most in each run."},{"name":"Region configs","description":"Read region configurations attached to a brand. Region configs drive scheduled report fan-out across markets."},{"name":"Locations","description":"The brand's real places (stores, offices, branches), added by hand, from a CSV or from its linked Google Business Profile locations: what a report measures as a market."},{"name":"Scheduled reports","description":"CRUD for scheduled report definitions. Each schedule fires a new report at the configured `frequency` (`daily`/`weekly`/`monthly`)."},{"name":"Jobs","description":"Poll the status of asynchronous jobs (e.g. report generation). Each job is principal-isolated: keys can only see jobs they started; brand-restricted keys can only see jobs for their brand."},{"name":"Page audit","description":"Run a rule-based SEO/AEO best-practice audit on any public page and get an overall score plus concrete recommendations. Costs 1 credit per run; ideal for CI checks via the GitHub Action."},{"name":"Citations","description":"Per-brand URL citations powering the outreach pipeline. List, filter and roll up the pages where the brand appeared (or could appear) across AI assistants, with the **Outreach score** (field name `rankprompt_score`), domain authority, mention sentiment and per-platform mention counts."},{"name":"Fanouts","description":"The web searches the AI engines ran while answering the brand's prompts: what they looked up before citing a page, most frequent first, with the same report, schedule, engine and date filters as the citation reads."},{"name":"Exports","description":"A brand's whole citation and answer history as gzipped NDJSON files: start an export, poll it, download the files. The way to read everything, instead of paging the lists."},{"name":"Prompt discovery","description":"Questions and keywords worth tracking, from Search Console, the keywords the domain ranks for, keyword research, one page read by a model, the prompts competitors win and the engines' fan-out searches, each flagged when the brand already tracks it."},{"name":"Shares","description":"Time-limited public share links for **reports**, **scheduled reports**, **brand summaries** and **brand audits**. Each share is a read-only snapshot resolved at `/shared/{access_token}`. `POST` is idempotent; pass `rotate=true` to invalidate a leaked URL."},{"name":"Alias suggestions","description":"Detected name variants for a brand that are not yet counted as the brand. Accept the correct ones so future reports attribute those mentions, or dismiss the wrong ones."},{"name":"Competitors","description":"The brand's cross-report competitor registry: entities that show up alongside it in AI answers, ranked by share of voice. Reclassify, merge duplicates, or remove entities to keep the registry accurate."},{"name":"Content","description":"Report-driven content opportunities, ranked by impact: topics where competitors are cited and the brand is not. The highest-leverage list for AEO content work."},{"name":"Brand audits","description":"Full AI-visibility audits for a single market (country + language), with generated recommendations and citation analysis. Audit runs cost credits."},{"name":"SEO keywords","description":"Track Google keywords for a brand: positions over time, search volume and difficulty, keyword research, the organic overview and keyword gap against competitors, and the Google keyword behind each AI prompt. Buying provider data costs credits."},{"name":"SEO pages","description":"Track pages and run Lighthouse/PageSpeed audits plus technical SEO crawls on them. Includes Core Web Vitals history and ready-to-paste structured-data templates. Audits cost credits."},{"name":"Tasks","description":"The brand's action items (content, technical, outreach) created by report AI suggestions and the agent, with status and priority. Deleting a task requires OWNER access."},{"name":"Analytics","description":"Read the brand's Google Analytics 4 / Search Console connection status. Connecting a Google account is done in the app, not the API."},{"name":"Search Console","description":"Search data for a connected brand: Google Search Console's sitemaps, URL inspection and performance, and the same performance from Bing Webmaster Tools with `engine=bing`."},{"name":"Copilot Citations","description":"The pages Microsoft Copilot cited, from the Bing Webmaster Tools AI Performance exports a brand uploads in the app, each with the engines the brand's own reports saw cite it."},{"name":"OpenAI Ads","description":"Read-only reporting of the brand's OpenAI Ads (paid, labeled placements in ChatGPT): performance, attributed conversions and campaigns. Connecting the ad account is done in the app, not the API."},{"name":"Webhooks","description":"Register endpoints to receive event notifications (e.g. a report finishing), and inspect recent deliveries."},{"name":"Agency"},{"name":"Client reports"},{"name":"Community"},{"name":"Data Studio"},{"name":"Google Business Profile"},{"name":"Local rank"},{"name":"Merchant Center"},{"name":"Outreach"},{"name":"YouTube"}]}