{ "openapi": "3.1.0", "info": { "title": "Buzz Dealer AI API", "version": "1", "summary": "PR distribution and editorial publishing for AI agents, by Buzz Dealer.", "description": "The REST API of Buzz Dealer AI, by Buzz Dealer. The same operations as the MCP connector. Every request needs an API key (created by the account owner in the dashboard under Connections) as a bearer token. Rate limits per key (admin settings): 60 read requests and 10 ordering requests per minute by default; over a limit the answer is 429 with retry-after. Agents never pay: orders only reserve prepaid credits within the budget frame a person set. The same API key also works on the MCP server (Authorization: Bearer). Step by step for every AI client: https://buzzdealer.ai/connect.", "contact": { "name": "Buzz Dealer AI support", "email": "support@buzzdealer.ai", "url": "https://buzzdealer.ai/contact" } }, "servers": [ { "url": "https://api.buzzdealer.ai" } ], "externalDocs": { "description": "Connect your agent (every AI client, API keys)", "url": "https://buzzdealer.ai/connect?client=api" }, "x-connect": { "page": "https://buzzdealer.ai/connect", "mcp_server": "https://mcp.buzzdealer.ai/mcp", "docs": "https://buzzdealer.ai/docs", "llms_txt": "https://buzzdealer.ai/llms.txt" }, "x-mcp-tools": [ { "name": "find_publications", "title": "Find publications", "read_only": true, "spends_credits": false }, { "name": "get_publication", "title": "Get a publication", "read_only": true, "spends_credits": false }, { "name": "plan_campaign", "title": "Plan a campaign", "read_only": true, "spends_credits": false }, { "name": "get_ai_visibility_score", "title": "Get AI Visibility Score", "read_only": true, "spends_credits": false }, { "name": "check_company_presence", "title": "Quick reputation check of a company", "read_only": true, "spends_credits": false }, { "name": "check_originality_and_fit", "title": "Check originality and fit", "read_only": true, "spends_credits": false }, { "name": "quote_order", "title": "Quote an order", "read_only": false, "spends_credits": false }, { "name": "place_order", "title": "Place an order", "read_only": false, "spends_credits": true }, { "name": "get_order_status", "title": "Get order status", "read_only": true, "spends_credits": false }, { "name": "respond_to_replacement", "title": "Respond to a replacement offer", "read_only": false, "spends_credits": true }, { "name": "get_report", "title": "Get a report", "read_only": true, "spends_credits": false }, { "name": "order_audit", "title": "Order an audit", "read_only": false, "spends_credits": true }, { "name": "get_account_status", "title": "Get account status", "read_only": true, "spends_credits": false }, { "name": "get_linked_account", "title": "Which account is linked", "read_only": true, "spends_credits": false }, { "name": "start_radar", "title": "Start the scan", "read_only": false, "spends_credits": false }, { "name": "get_radar_status", "title": "Read the scan as it lands", "read_only": true, "spends_credits": false }, { "name": "get_questions", "title": "Get the next question", "read_only": true, "spends_credits": false }, { "name": "answer_question", "title": "Answer a question", "read_only": false, "spends_credits": false }, { "name": "set_preferences", "title": "Set the preferences", "read_only": false, "spends_credits": false }, { "name": "get_gaps", "title": "Get the gaps", "read_only": true, "spends_credits": false }, { "name": "start_fix", "title": "Start a fix", "read_only": false, "spends_credits": false }, { "name": "mark_fix_done", "title": "Mark a fix done and verify it", "read_only": false, "spends_credits": false }, { "name": "get_progress", "title": "Get the progress", "read_only": true, "spends_credits": false }, { "name": "what_changed", "title": "What changed", "read_only": true, "spends_credits": false }, { "name": "get_playbook", "title": "Get the Reputation Agent playbook", "read_only": true, "spends_credits": false }, { "name": "check_request", "title": "Check a borderline request (three lanes)", "read_only": true, "spends_credits": false }, { "name": "rate_fix", "title": "Record whether a fix worked", "read_only": false, "spends_credits": false }, { "name": "radar_scan", "title": "Run the Radar (same as start_radar)", "read_only": false, "spends_credits": false }, { "name": "plan_fixes", "title": "Plan fixes (same as get_gaps)", "read_only": true, "spends_credits": false }, { "name": "get_reputation_profile", "title": "Get the reputation profile", "read_only": true, "spends_credits": false }, { "name": "update_reputation_profile", "title": "Update the reputation profile", "read_only": false, "spends_credits": false }, { "name": "confirm_statement", "title": "Confirm or correct a statement (same as answer_question)", "read_only": false, "spends_credits": false } ], "security": [ { "bearerAuth": [] } ], "paths": { "/v1/account": { "get": { "operationId": "get_account", "summary": "Balance, budget frame, pending approvals and what the monthly plan still includes this month (read only)", "description": "Same behavior as the MCP tool get_account_status.", "tags": [ "get_account_status" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "brand_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "Optional: a brand id of this account, to include that brand's budget frame" } ] } }, "/v1/publications": { "get": { "operationId": "get_publications", "summary": "Search published catalog items", "description": "Same behavior as the MCP tool find_publications.", "tags": [ "find_publications" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Publication" } } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "product_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "site", "pr_package", "bundle", "program", "service" ] }, "description": "site (an article on one site), pr_package (wire distribution), bundle, program (monthly), service" }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100 }, "description": "Exact category, for example Finance" }, { "name": "region", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100 }, "description": "For example UK, US, LATAM" }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 40 }, "description": "Language as an ISO 639-1 code (en, es, pt) or its English name (English); any case" }, { "name": "max_price_cents", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "description": "Highest price per item, in US cents" }, { "name": "dofollow", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Sites only: true for dofollow links" }, { "name": "min_dr", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 100 }, "description": "Sites only: lowest DR (Ahrefs), 0 to 100. Items without a DR never match" }, { "name": "query", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100 }, "description": "Words to look for in name, domain, category or description" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50 }, "description": "At most this many results (default 10, at most 50)" }, { "name": "goal", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "reputation", "seo", "ai_visibility", "mentions" ] }, "description": "Optional: rank the results for one goal (reputation, seo, ai_visibility or mentions) instead of by AI score" }, { "name": "goal_weights", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[a-z_]+:\\d+(\\.\\d+)?(,[a-z_]+:\\d+(\\.\\d+)?)*$" }, "description": "A goal mix instead of goal, as goal:weight pairs, for example ai_visibility:60,seo:40. Goals: reputation, seo, ai_visibility, mentions; each 0 to 100; scaled to 100 when they do not add up; all zero is refused" } ] } }, "/v1/publications/{item_id}": { "get": { "operationId": "get_publications_item_id", "summary": "One published item with its required inputs", "description": "Same behavior as the MCP tool get_publication.", "tags": [ "get_publication" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/Publication" } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "item_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "An item id from find_publications" } ] } }, "/v1/quotes": { "post": { "operationId": "post_quotes", "summary": "Price items and lock the quote (moves no credits)", "description": "Same behavior as the MCP tool quote_order.", "tags": [ "quote_order" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "item_id": { "description": "The item id from find_publications or plan_campaign", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "domain": { "description": "Or a site's domain, for example example.com: used when exactly one published site has it; when several do, the answer lists them with their ids", "type": "string", "minLength": 3, "maxLength": 253 }, "add_ons": { "type": "object", "properties": { "writing": { "description": "Our writers write it (priced per article or release)", "type": "boolean" }, "logo": { "description": "PR packages only", "type": "boolean" } } }, "inputs": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "maxLength": 30000 }, "description": "Customer inputs as text fields. Releases: release_text or release_url, company_name, contact_name, contact_email; optional contact_phone, preferred_date (YYYY-MM-DD) and logo_url. Articles: article_text (or brief with the writing add-on), target_url, anchor_text. Audits: brand_name (brand or person name), website; personal audit also relationship (myself, my_company or client). Any: notes." } } }, "description": "1 to 50 items, each by item_id (from find_publications) or a site's domain, with optional add-ons and inputs" }, "brand_id": { "description": "Optional. A brand of this account (listed in the dashboard under Brands); items for an unverified brand wait for its verification before fulfilment", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "items" ] } } } } } }, "/v1/orders": { "get": { "operationId": "get_orders", "summary": "The 10 most recent orders", "description": "Same behavior as the MCP tool get_order_status.", "tags": [ "get_order_status" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "post_orders", "summary": "Place an order from a quote (reserves credits)", "description": "Same behavior as the MCP tool place_order.", "tags": [ "place_order" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A unique value per order or credit transfer (8 to 120 characters). Used as idempotency_key when the body does not carry one. A retry with the same value never places the order or moves the credits twice.", "schema": { "type": "string", "minLength": 8, "maxLength": 120 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "quote_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "From quote_order; the prices stay locked until locked_until" }, "idempotency_key": { "type": "string", "minLength": 8, "maxLength": 120, "description": "A unique value per order. Send the same value again only to retry the same order; it is never placed twice." }, "inputs": { "description": "Inputs per quote line id (line_id from quote_order), for lines that did not get them with the quote. A site's domain also works as the key when exactly one line of the quote is on it", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "maxLength": 30000 }, "description": "Customer inputs as text fields. Releases: release_text or release_url, company_name, contact_name, contact_email; optional contact_phone, preferred_date (YYYY-MM-DD) and logo_url. Articles: article_text (or brief with the writing add-on), target_url, anchor_text. Audits: brand_name (brand or person name), website; personal audit also relationship (myself, my_company or client). Any: notes." } }, "notes": { "type": "string", "maxLength": 2000 } }, "required": [ "quote_id", "idempotency_key" ] } } } } } }, "/v1/orders/{order_id}": { "get": { "operationId": "get_orders_order_id", "summary": "One order: items, links, delays, replacement offers", "description": "Same behavior as the MCP tool get_order_status.", "tags": [ "get_order_status" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "One order; leave out for the 10 most recent orders" } ] } }, "/v1/replacements/{offer_id}": { "post": { "operationId": "post_replacements_offer_id", "summary": "Accept a replacement, or take the credits back to the balance", "description": "Same behavior as the MCP tool respond_to_replacement.", "tags": [ "respond_to_replacement" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "offer_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "replacement_offer.offer_id from get_order_status" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "choice": { "type": "string", "enum": [ "accept", "refund" ], "description": "accept: order the proposed replacement now (its price is reserved); \"refund\" (the value kept for older clients): credits back to your balance, no card refund. Example: \"accept\"" } }, "required": [ "choice" ] } } } } } }, "/v1/campaign-plans": { "post": { "operationId": "post_campaign_plans", "summary": "A deterministic campaign plan (read only)", "description": "Same behavior as the MCP tool plan_campaign.", "tags": [ "plan_campaign" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "goal": { "description": "One goal: reputation, seo, ai_visibility or mentions. Or send goal_weights for a mix; send neither to use the goals set in the dashboard (Budget and goals)", "type": "string", "enum": [ "reputation", "seo", "ai_visibility", "mentions" ] }, "goal_weights": { "type": "object", "properties": { "reputation": { "type": "number", "minimum": 0, "maximum": 100 }, "seo": { "type": "number", "minimum": 0, "maximum": 100 }, "ai_visibility": { "type": "number", "minimum": 0, "maximum": 100 }, "mentions": { "type": "number", "minimum": 0, "maximum": 100 } }, "additionalProperties": false, "description": "A goal mix instead of goal: any of reputation, seo, ai_visibility, mentions, each 0 to 100, for example {\"ai_visibility\": 60, \"seo\": 40}. Weights that do not sum to 100 are scaled to 100; all zero is refused" }, "brand_id": { "description": "Optional. A brand of this account. With goal_weights or no goal, the goal of its weakest audit score (sentiment: reputation, authority: seo, discoverability: ai_visibility) gets more weight, and its budget frame goals are the default. With one goal, that goal stays at 100% and the plan adds a tip", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "topic": { "type": "string", "minLength": 2, "maxLength": 60, "description": "Topic or category, for example fintech" }, "region": { "type": "string", "minLength": 2, "maxLength": 100, "description": "For example UK" }, "language": { "description": "Optional. An ISO 639-1 code (en) or its English name (English); any case", "type": "string", "maxLength": 40 }, "budget_cents": { "type": "integer", "minimum": 100, "maximum": 100000000, "description": "Total budget in US cents; the plan never exceeds it" } }, "required": [ "topic", "region", "budget_cents" ] } } } } } }, "/v1/checks": { "post": { "operationId": "post_checks", "summary": "Originality, content rules and fit check of a text (free up to a monthly limit)", "description": "Same behavior as the MCP tool check_originality_and_fit.", "tags": [ "check_originality_and_fit" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "minLength": 20, "maxLength": 30000, "description": "The full article or press release to check" }, "item_id": { "description": "Optional: a published item from find_publications, to check the fit against its word, link, language and topic rules", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "text" ] } } } } } }, "/v1/reports": { "post": { "operationId": "post_reports", "summary": "Report for one order, or one brand over a date range", "description": "Same behavior as the MCP tool get_report.", "tags": [ "get_report" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "order_id": { "description": "Report one order", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "brand_id": { "description": "Or report one brand over a date range", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "from": { "description": "YYYY-MM-DD, with brand_id (default: 90 days ago)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "to": { "description": "YYYY-MM-DD inclusive, with brand_id (default: today)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } } } } } } } }, "/v1/ai-visibility-scores": { "post": { "operationId": "post_ai_visibility_scores", "summary": "AI score (beta) and tier for catalog outlets by domain", "description": "Same behavior as the MCP tool get_ai_visibility_score.", "tags": [ "get_ai_visibility_score" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domains": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 3, "maxLength": 253 }, "description": "Domains, for example example.com" } }, "required": [ "domains" ] } } } } } }, "/v1/audits": { "post": { "operationId": "post_audits", "summary": "Order one audit for a brand or person of the account: brand audit, personal audit, Wikipedia notability check, website analysis, Brand ORM status report or Personal ORM status report (reserves credits)", "description": "Same behavior as the MCP tool order_audit.", "tags": [ "order_audit" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "audit_type": { "type": "string", "enum": [ "brand_audit", "personal_audit", "wikipedia_notability", "website_analysis", "brand_orm", "personal_orm" ], "description": "brand_audit (sentiment, authority and discoverability scores for a brand), personal_audit (the same scores for a person), wikipedia_notability (whether the brand or person is likely notable enough for Wikipedia), website_analysis (an analysis report of one website), brand_orm (Brand ORM status report: where a brand's online reputation stands now, in search, AI answers and the press), personal_orm (Personal ORM status report: the same for a person)" }, "brand_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The brand or person of this account the audit is about (listed in the dashboard under Brands); the report is kept with it. Items for an unverified brand wait for its verification before fulfilment" }, "name": { "description": "The brand or person name to audit; defaults to the brand's name", "type": "string", "maxLength": 200 }, "website": { "description": "https link; for website_analysis the website to analyse (required when the brand has no website)", "type": "string", "maxLength": 2000 }, "relationship": { "description": "personal_audit only, required: who the person is to you: myself, my_company (someone in my company) or client (a client I represent)", "type": "string", "enum": [ "myself", "my_company", "client" ] }, "role": { "description": "personal_audit only, optional: the person's role, for example \"CEO, Acme\"", "type": "string", "maxLength": 200 }, "idempotency_key": { "type": "string", "minLength": 8, "maxLength": 120, "description": "A unique value per audit order; send it again only to retry the same order" } }, "required": [ "audit_type", "brand_id", "idempotency_key" ] } } } } } }, "/v1/reputation/radar": { "post": { "operationId": "post_reputation_radar", "summary": "Start the scan of you, your company, or both", "description": "Same behavior as the MCP tool start_radar.", "tags": [ "start_radar" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "for": { "description": "Who the Agent is for: person (me), brand (my company) or founder (both). Asked once; leave out after that", "type": "string", "enum": [ "person", "brand", "founder" ] }, "name": { "description": "Me: the account holder's full name. The Agent scans only the account holder and the account's own company", "type": "string", "minLength": 2, "maxLength": 120 }, "role": { "description": "Me: role or profession", "type": "string", "maxLength": 80 }, "organization": { "description": "Me: company or organization", "type": "string", "maxLength": 120 }, "place": { "description": "Me: city or country", "type": "string", "maxLength": 80 }, "link": { "description": "Me: one link that is mine (my site or a profile)", "type": "string", "maxLength": 500 }, "company": { "description": "My company: name and domain, plus category, best known for and up to 3 competitors", "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 120, "description": "The company's name" }, "domain": { "type": "string", "minLength": 3, "maxLength": 200, "description": "The company's website domain, for example example.com" }, "category": { "description": "The category in a few words, for example \"logistics software\"", "type": "string", "maxLength": 80 }, "best_known_for": { "description": "What it is best known for, for example \"boutique hotels in Lisbon\"", "type": "string", "maxLength": 120 }, "competitors": { "description": "Up to 3 competitors, name and domain", "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "domain": { "type": "string", "minLength": 3, "maxLength": 200 } }, "required": [ "name", "domain" ] } } }, "required": [ "name", "domain" ] }, "paid": { "description": "The included rescan of this period is used and the person said yes, in this conversation, to a fresh scan now at the price start_radar showed: buys the paid rescan (with too little balance it waits until a person adds credits in their dashboard). Never without the person's yes, and never set on your own", "type": "boolean" }, "idempotency_key": { "description": "With paid: a unique key, reused only to retry the same purchase", "type": "string", "minLength": 8, "maxLength": 120 } } } } } } }, "get": { "operationId": "get_reputation_radar", "summary": "Read the scan as it lands (items after a sequence number)", "description": "Same behavior as the MCP tool get_radar_status.", "tags": [ "get_radar_status" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "run_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "The run from start_radar (default: the account's latest scan)" }, { "name": "after_seq", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "description": "Only findings that landed after this sequence number (send the last_seq of the previous call)" } ] } }, "/v1/reputation/questions": { "get": { "operationId": "get_reputation_questions", "summary": "The next question the scan could not answer itself", "description": "Same behavior as the MCP tool get_questions.", "tags": [ "get_questions" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "entity_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "The person or the company (default: the person, else the company)" } ] }, "post": { "operationId": "post_reputation_questions", "summary": "Answer a question; the result changes at once", "description": "Same behavior as the MCP tool answer_question.", "tags": [ "answer_question" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "question_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The question_id from get_questions" }, "choice": { "type": "string", "minLength": 1, "maxLength": 40, "description": "One of the question's choice ids, or skip" }, "correction": { "description": "For a statement the person says is wrong: the right fact, in their words", "type": "string", "maxLength": 300 } }, "required": [ "question_id", "choice" ] } } } } } }, "/v1/reputation/preferences": { "post": { "operationId": "post_reputation_preferences", "summary": "Alerts, summary, goal and markets", "description": "Same behavior as the MCP tool set_preferences.", "tags": [ "set_preferences" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "alerts": { "description": "Where alerts go: email, ai (here, in this chat) or both", "type": "string", "enum": [ "email", "ai", "both" ] }, "summary": { "description": "How often a summary email comes", "type": "string", "enum": [ "weekly", "monthly", "off" ] }, "goal": { "description": "The main goal: found_correctly, fix_negative, recommended_by_ai or win_press", "type": "string", "enum": [ "found_correctly", "fix_negative", "recommended_by_ai", "win_press" ] }, "markets": { "description": "Markets that matter (country and language). How many are scanned depends on the account's plan", "maxItems": 5, "type": "array", "items": { "type": "object", "properties": { "country": { "type": "string", "pattern": "^([A-Za-z]{2}|GLOBAL)$", "description": "ISO country code, such as US or DE" }, "language": { "type": "string", "pattern": "^[A-Za-z]{2}$", "description": "ISO language code, such as en or de" } }, "required": [ "country", "language" ] } } } } } } } } }, "/v1/reputation/gaps": { "get": { "operationId": "get_reputation_gaps", "summary": "The gaps, ranked, quick wins first, each with its fix", "description": "Same behavior as the MCP tool get_gaps.", "tags": [ "get_gaps" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "entity_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "The person or the company (default: the person, else the company)" } ] } }, "/v1/reputation/fixes": { "post": { "operationId": "post_reputation_fixes", "summary": "The brief for one fix, from your verified facts", "description": "Same behavior as the MCP tool start_fix.", "tags": [ "start_fix" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "gap_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The gap_id from get_gaps" } }, "required": [ "gap_id" ] } } } } } }, "/v1/reputation/fixes/done": { "post": { "operationId": "post_reputation_fixes_done", "summary": "Mark a fix done; it is checked at once where it can be", "description": "Same behavior as the MCP tool mark_fix_done.", "tags": [ "mark_fix_done" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "gap_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The gap_id from get_gaps" }, "url": { "description": "The page or profile where the fix is live (for the instant check)", "type": "string", "maxLength": 500 } }, "required": [ "gap_id" ] } } } } } }, "/v1/reputation/progress": { "get": { "operationId": "get_reputation_progress", "summary": "Score history, fixes done and verified", "description": "Same behavior as the MCP tool get_progress.", "tags": [ "get_progress" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/reputation/changes": { "get": { "operationId": "get_reputation_changes", "summary": "What changed since the previous scan", "description": "Same behavior as the MCP tool what_changed.", "tags": [ "what_changed" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "entity_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "The person or the company (default: the person, else the company)" } ] } }, "/v1/reputation/playbook": { "get": { "operationId": "get_reputation_playbook", "summary": "The Reputation Agent playbook (versioned)", "description": "Same behavior as the MCP tool get_playbook.", "tags": [ "get_playbook" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/reputation/requests": { "post": { "operationId": "post_reputation_requests", "summary": "Sort a borderline request into one of three lanes", "description": "Same behavior as the MCP tool check_request.", "tags": [ "check_request" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "request": { "type": "string", "minLength": 3, "maxLength": 1000, "description": "The person's request in English (translate it first), without names or private details" } }, "required": [ "request" ] } } } } } }, "/v1/reputation/fixes/outcome": { "post": { "operationId": "post_reputation_fixes_outcome", "summary": "Record whether a fix worked, in the person's words", "description": "Same behavior as the MCP tool rate_fix.", "tags": [ "rate_fix" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "gap_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The gap_id of the fix" }, "worked": { "type": "boolean", "description": "true: the person says it worked; false: it did not" } }, "required": [ "gap_id", "worked" ] } } } } } }, "/v1/reputation/radar-scans": { "post": { "operationId": "post_reputation_radar_scans", "summary": "Same as POST /v1/reputation/radar (older name)", "description": "Same behavior as the MCP tool radar_scan.", "tags": [ "radar_scan" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 120, "description": "The account holder's full name, or the account's company name with kind brand" }, "kind": { "description": "person (default) or brand", "type": "string", "enum": [ "person", "brand" ] }, "role": { "type": "string", "maxLength": 80 }, "organization": { "type": "string", "maxLength": 120 }, "place": { "type": "string", "maxLength": 80 }, "link": { "type": "string", "maxLength": 500 }, "domain": { "description": "Brands: the website domain", "type": "string", "minLength": 3, "maxLength": 200 }, "category": { "type": "string", "maxLength": 80 }, "best_known_for": { "type": "string", "maxLength": 120 }, "competitors": { "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "domain": { "type": "string", "minLength": 3, "maxLength": 200 } }, "required": [ "name", "domain" ] } } }, "required": [ "name" ] } } } } } }, "/v1/reputation/plans": { "get": { "operationId": "get_reputation_plans", "summary": "Same as GET /v1/reputation/gaps (older name)", "description": "Same behavior as the MCP tool plan_fixes.", "tags": [ "plan_fixes" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "entity_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "The person or the company (default: the person, else the company)" } ] } }, "/v1/reputation/profiles": { "get": { "operationId": "get_reputation_profiles", "summary": "The person and the company the agent works for (older name)", "description": "Same behavior as the MCP tool get_reputation_profile.", "tags": [ "get_reputation_profile" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "profile_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "The person or the company (default: all of the account's)" } ] }, "post": { "operationId": "post_reputation_profiles", "summary": "Update who the agent works for (older name)", "description": "Same behavior as the MCP tool update_reputation_profile.", "tags": [ "update_reputation_profile" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "profile_id": { "description": "The person or the company to change (default: the person)", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "create": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "person", "brand" ] }, "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "domain": { "type": "string", "maxLength": 200 } }, "required": [ "kind" ] }, "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "facts": { "type": "object", "properties": { "roles": { "maxItems": 20, "type": "array", "items": { "type": "string", "maxLength": 120 } }, "organizations": { "maxItems": 20, "type": "array", "items": { "type": "string", "maxLength": 120 } }, "places": { "maxItems": 5, "type": "array", "items": { "type": "string", "maxLength": 80 } }, "links": { "maxItems": 30, "type": "array", "items": { "type": "string", "maxLength": 500, "format": "uri" } }, "key_facts": { "maxItems": 20, "type": "array", "items": { "type": "string", "maxLength": 300 } }, "category": { "type": "string", "maxLength": 80 }, "best_known_for": { "type": "string", "maxLength": 120 }, "competitors": { "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "domain": { "type": "string", "minLength": 3, "maxLength": 200 } }, "required": [ "name", "domain" ] } } } }, "namesakes": { "description": "Other people or companies with the same name, as the person describes them", "maxItems": 20, "type": "array", "items": { "type": "string", "maxLength": 300 } }, "results": { "description": "Answer for results, each with one answer, and change an earlier answer the same way. This is mine: my own site, page or profile. This is about me: someone else wrote it about me, so it counts as independent coverage. Not me: it is about someone else, so it leaves every count. (mine true or false still works: true is mine, false is not me.)", "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2000, "format": "uri" }, "answer": { "type": "string", "enum": [ "mine", "about_me", "not_me" ] }, "mine": { "type": [ "boolean", "null" ] } }, "required": [ "url" ] } } } } } } } } }, "/v1/reputation/statements": { "post": { "operationId": "post_reputation_statements", "summary": "Same as answering a fact question (older name)", "description": "Same behavior as the MCP tool confirm_statement.", "tags": [ "confirm_statement" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "statement_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The question_id of a statement to check, from get_questions" }, "verdict": { "type": "string", "enum": [ "correct", "wrong" ] }, "corrected_text": { "type": "string", "minLength": 3, "maxLength": 300 } }, "required": [ "statement_id", "verdict" ] } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "An API key from the dashboard (Connections)" } }, "schemas": { "Error": { "type": "object", "description": "Every error has these three fields. next_step tells the caller exactly what to do.", "properties": { "error": { "type": "string", "description": "Machine-readable code, for example insufficient_credits" }, "message": { "type": "string", "description": "What happened, in plain words" }, "next_step": { "type": "string", "description": "What to do next" } }, "required": [ "error", "message", "next_step" ], "additionalProperties": true }, "Publication": { "type": "object", "additionalProperties": true, "required": [ "id", "product_type", "name", "price_cents", "currency" ], "properties": { "id": { "type": "string", "format": "uuid" }, "product_type": { "type": "string", "enum": [ "site", "pr_package", "bundle", "program", "service" ] }, "name": { "type": "string" }, "domain": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "region": { "type": [ "string", "null" ] }, "languages": { "type": "array", "items": { "type": "string" } }, "price_cents": { "type": [ "integer", "null" ], "description": "Price in US cents" }, "price": { "type": [ "string", "null" ], "description": "Price in US dollars, for display" }, "currency": { "const": "USD" }, "ai_score": { "type": [ "integer", "null" ], "description": "AI score (beta), 0 to 100" }, "tier": { "type": [ "string", "null" ] }, "dr": { "type": "integer", "minimum": 0, "maximum": 100, "description": "DR (Ahrefs) of the site's domain. Single sites only; absent when we have no DR" }, "dr_label": { "const": "DR (Ahrefs)" }, "dofollow": { "type": [ "boolean", "null" ] }, "min_word_count": { "type": [ "integer", "null" ], "description": "Sites: the fewest words the site takes (fit check); null when none is recorded" }, "max_word_count": { "type": [ "integer", "null" ], "description": "Sites: the most words the site takes (fit check). Release on livepublicator.com: 800" }, "max_links": { "type": [ "integer", "null" ], "description": "Sites: the most links the site takes (fit check). Release on livepublicator.com: 3" }, "service_notes": { "type": [ "string", "null" ], "description": "Release on livepublicator.com only: what happens to the release. The text is kept and lightly edited for style; a short summary, key facts and an FAQ are added; a person may review it first (usually within 24 hours); English only, 300 to 20,000 characters with the headline, at most 800 words and 3 https links; cover image (image_url) an https JPEG, PNG or WebP of at most 5 MB; no AI-generated images. No writing add-on. Contact details come from the order, else the brand's press contact" }, "add_ons": { "type": "object", "properties": { "writing": { "type": [ "integer", "null" ], "description": "Writing add-on price in US cents, or null when not offered" }, "logo": { "type": [ "integer", "null" ], "description": "Logo add-on price in US cents for this PR package, or null when it has no logo option" } } } } } }, "responses": { "Error": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }