{ "openapi": "3.1.0", "info": { "title": "SERPpro API", "version": "1.0.0", "description": "Programmatic access to the SERPpro link-building platform: browse the publisher marketplace, place orders, check balance, find PR opportunities, generate AI pitches, and run SEO analyses.\n\n**Designed for ChatGPT Custom GPT Actions, Zapier, n8n, Make, and any HTTP client.**\n\nFallback base URL (if the Cloudflare proxy is unavailable): https://vzyinpfiextyelxpmnnu.supabase.co/functions/v1/api-v1", "contact": { "name": "SERPpro Support", "url": "https://app.serppro.ai/support", "email": "support@serppro.ai" }, "termsOfService": "https://app.serppro.ai/legal/api-terms", "x-logo": { "url": "https://app.serppro.ai/serppro-logo.png", "altText": "SERPpro" } }, "servers": [ { "url": "https://api.serppro.ai/rest", "description": "Production" } ], "tags": [ { "name": "Marketplace", "description": "Publisher discovery and inventory" }, { "name": "Orders", "description": "Place and track backlink orders" }, { "name": "Account", "description": "Balance and account info" }, { "name": "PR", "description": "Journalist requests and pitches" }, { "name": "Content", "description": "AI content generation and humanization" }, { "name": "Analysis", "description": "Anchor, gap, audit, and rank tracking" }, { "name": "Backlink Intelligence", "description": "Page-level link gap plans and recommended placements" }, { "name": "Backlink Monitor", "description": "Live/lost/indexed tracking of your backlinks" }, { "name": "Traffic Analytics", "description": "Monitored target pages and traffic history" }, { "name": "Projects", "description": "SEO projects, Site Insights and saved data" }, { "name": "Webhooks", "description": "Outbound event subscriptions" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "sp_live_...", "description": "API key generated at https://app.serppro.ai/api-keys" } }, "schemas": { "Publisher": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "domain": { "type": "string", "description": "Partially masked (e.g. exa***.com)" }, "dr": { "type": "number" }, "da": { "type": "number" }, "traffic": { "type": "number" }, "niche": { "type": "string" }, "country": { "type": "string" }, "price": { "type": "string", "description": "USD price, e.g. \"$150\"" }, "link_type": { "type": "string" }, "tat": { "type": "string", "description": "Turnaround time" }, "approval_available": { "type": "boolean" } } }, "OrderItem": { "type": "object", "required": [ "publisher_id", "target_url", "anchor_text" ], "properties": { "publisher_id": { "type": "string", "format": "uuid" }, "target_url": { "type": "string", "format": "uri" }, "anchor_text": { "type": "string" }, "special_note": { "type": "string" } } }, "Error": { "type": "object", "properties": { "error": { "type": "string" } } } } }, "security": [ { "bearerAuth": [] } ], "paths": { "/publishers": { "get": { "operationId": "listPublishers", "tags": [ "Marketplace" ], "summary": "Search the publisher marketplace", "description": "Browse available link-building publishers with filters. Domains are partially masked until an order is placed.", "security": [], "parameters": [ { "name": "min_dr", "in": "query", "schema": { "type": "number" }, "description": "Minimum Domain Rating (0-100)" }, { "name": "max_dr", "in": "query", "schema": { "type": "number" } }, { "name": "min_da", "in": "query", "schema": { "type": "number" } }, { "name": "max_price", "in": "query", "schema": { "type": "number" }, "description": "Max price in USD" }, { "name": "niche", "in": "query", "schema": { "type": "string" }, "description": "e.g. Technology, Health" }, { "name": "country", "in": "query", "schema": { "type": "string" }, "description": "ISO country code, e.g. US, UK" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Substring match on domain" }, { "name": "limit", "in": "query", "schema": { "type": "number", "default": 20, "maximum": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "number", "default": 0 } } ], "responses": { "200": { "description": "List of publishers", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "number" }, "publishers": { "type": "array", "items": { "$ref": "#/components/schemas/Publisher" } } } } } } } } } }, "/balance": { "get": { "operationId": "getBalance", "tags": [ "Account" ], "summary": "Get account balance", "responses": { "200": { "description": "Current balance", "content": { "application/json": { "schema": { "type": "object", "properties": { "balance": { "type": "string", "example": "$120.00" }, "total_deposited": { "type": "string" }, "total_spent": { "type": "string" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orders": { "get": { "operationId": "listOrders", "tags": [ "Orders" ], "summary": "List your orders", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "number", "default": 10, "maximum": 50 } } ], "responses": { "200": { "description": "List of orders" } } }, "post": { "operationId": "createOrder", "tags": [ "Orders" ], "x-openai-isConsequential": true, "summary": "Place a backlink order", "description": "Creates a new order with one or more line items. Each item targets a publisher with a target URL and anchor text. Total cost is deducted from your balance.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/OrderItem" } }, "notes": { "type": "string" } } } } } }, "responses": { "200": { "description": "Order created" }, "402": { "description": "Insufficient balance" } } } }, "/orders/{order_id}": { "get": { "operationId": "getOrder", "tags": [ "Orders" ], "summary": "Get order details", "parameters": [ { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Order details with items and live URLs" } } } }, "/pr-opportunities": { "get": { "operationId": "listPrOpportunities", "tags": [ "PR" ], "summary": "List PR / journalist opportunities", "description": "Recent journalist requests scraped from X, SOS, MentionMatch, SourceBottle, and Reddit.", "security": [], "parameters": [ { "name": "source", "in": "query", "schema": { "type": "string", "enum": [ "all", "X", "SOS", "MentionMatch", "SourceBottle", "Reddit" ] } }, { "name": "keyword", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "number", "default": 10, "maximum": 25 } } ], "responses": { "200": { "description": "Opportunity list" } } } }, "/pitches": { "post": { "operationId": "generatePitch", "tags": [ "PR" ], "x-openai-isConsequential": true, "summary": "Generate an AI pitch for a PR opportunity", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "opportunity_id" ], "properties": { "opportunity_id": { "type": "string" }, "expert_id": { "type": "string", "description": "Optional — defaults to your first active expert" } } } } } }, "responses": { "200": { "description": "Returns pitch_id" } } } }, "/pitches/{pitch_id}/send": { "post": { "operationId": "sendPitch", "tags": [ "PR" ], "x-openai-isConsequential": true, "summary": "Send a generated pitch", "parameters": [ { "name": "pitch_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "to_address": { "type": "string", "format": "email", "description": "Override detected journalist email" }, "subject": { "type": "string" } } } } } }, "responses": { "200": { "description": "Queued for delivery" } } } }, "/experts": { "get": { "operationId": "listExperts", "tags": [ "PR" ], "summary": "List your expert profiles", "responses": { "200": { "description": "OK" } } } }, "/anchor-analysis": { "post": { "operationId": "startAnchorAnalysis", "tags": [ "Analysis" ], "x-openai-isConsequential": true, "summary": "Run anchor text analysis (10 credits)", "description": "Starts a backlink anchor analysis comparing your domain to top SERP competitors. Returns job_id; poll GET /anchor-analysis/{id}.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain", "keyword" ], "properties": { "domain": { "type": "string", "example": "example.com" }, "keyword": { "type": "string", "example": "best running shoes" }, "location_code": { "type": "number", "description": "DataForSEO location (default 2840 = US)" } } } } } }, "responses": { "200": { "description": "Job started" }, "402": { "description": "Insufficient credits" } } } }, "/anchor-analysis/{id}": { "get": { "operationId": "getAnchorAnalysis", "tags": [ "Analysis" ], "summary": "Get anchor analysis result", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Status or completed result" } } } }, "/humanize": { "post": { "operationId": "humanizeText", "tags": [ "Content" ], "x-openai-isConsequential": true, "summary": "Humanize AI text (2 credits)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "50-15000 chars" }, "strength": { "type": "string", "enum": [ "More Human", "Quality", "Balanced" ] }, "readability": { "type": "string", "enum": [ "High School", "University", "Doctorate", "Journalist", "Marketing" ] } } } } } }, "responses": { "200": { "description": "Returns document_id" } } } }, "/humanize/{document_id}": { "get": { "operationId": "getHumanizedText", "tags": [ "Content" ], "summary": "Poll humanize result", "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Humanized text payload" } } } }, "/detect-ai": { "post": { "operationId": "detectAi", "tags": [ "Content" ], "x-openai-isConsequential": true, "summary": "AI detection (1 credit)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "Min 50 chars" } } } } } }, "responses": { "200": { "description": "ai_score 0-100" } } } }, "/backlink-intelligence/runs": { "get": { "operationId": "listBacklinkIntelligenceRuns", "tags": [ "Backlink Intelligence" ], "summary": "List Backlink Intelligence runs", "parameters": [ { "name": "project_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "number", "default": 10, "maximum": 50 } } ], "responses": { "200": { "description": "OK" } } }, "post": { "operationId": "runBacklinkIntelligence", "tags": [ "Backlink Intelligence" ], "x-openai-isConsequential": true, "summary": "Run Backlink Intelligence on a project", "description": "Audits every important page, compares referring domains against SERP rivals, and returns a page-by-page link plan plus a recommended publisher shortlist.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "project_id" ], "properties": { "project_id": { "type": "string", "format": "uuid", "description": "From GET /projects" }, "keyword": { "type": "string", "description": "Optional focus keyword" } } } } } }, "responses": { "200": { "description": "Run summary, tasks and recommended placements" } } } }, "/backlink-intelligence/plan": { "get": { "operationId": "getBacklinkPlan", "tags": [ "Backlink Intelligence" ], "summary": "Page-by-page link plan", "description": "Pass run_id, or project_id to use its latest completed run.", "parameters": [ { "name": "run_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "project_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "number", "default": 50, "maximum": 200 } } ], "responses": { "200": { "description": "OK" } } } }, "/placements/recommended": { "get": { "operationId": "listRecommendedPlacements", "tags": [ "Backlink Intelligence" ], "summary": "Recommended placements for a run", "description": "Ranked publishers with price, target URL, suggested anchor and reason. Order them via POST /placements/recommended/order.", "parameters": [ { "name": "run_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "project_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "task_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "max_price", "in": "query", "schema": { "type": "number" }, "description": "Max price per placement in USD" }, { "name": "limit", "in": "query", "schema": { "type": "number", "default": 25, "maximum": 100 } } ], "responses": { "200": { "description": "OK" } } } }, "/placements/recommended/order": { "post": { "operationId": "orderRecommendedPlacements", "tags": [ "Orders" ], "x-openai-isConsequential": true, "summary": "Buy recommended placements from your balance", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "placement_ids" ], "properties": { "placement_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "placement_id values from GET /placements/recommended (max 50)" }, "target_url": { "type": "string", "format": "uri", "description": "Optional override target URL" }, "notes": { "type": "string" } } } } } }, "responses": { "200": { "description": "order_id, total, items_count, skipped" }, "402": { "description": "Insufficient balance" } } } }, "/monitor/monitors": { "get": { "operationId": "listBacklinkMonitors", "tags": [ "Backlink Monitor" ], "summary": "List Backlink Monitor jobs", "parameters": [ { "name": "project_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "number", "default": 25, "maximum": 100 } } ], "responses": { "200": { "description": "OK" } } } }, "/monitor/links": { "get": { "operationId": "listMonitoredBacklinks", "tags": [ "Backlink Monitor" ], "summary": "List monitored backlinks", "parameters": [ { "name": "monitor_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "project_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "live", "lost", "not_indexed", "nofollow", "all" ] } }, { "name": "limit", "in": "query", "schema": { "type": "number", "default": 50, "maximum": 200 } } ], "responses": { "200": { "description": "OK" } } } }, "/monitor/changes": { "get": { "operationId": "listBacklinkChanges", "tags": [ "Backlink Monitor" ], "summary": "Backlink change log (lost, restored, de-indexed, anchor edits)", "parameters": [ { "name": "monitor_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "change_type", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "number", "default": 50, "maximum": 200 } } ], "responses": { "200": { "description": "OK" } } } }, "/traffic-analytics/pages": { "get": { "operationId": "listTrafficPages", "tags": [ "Traffic Analytics" ], "summary": "Monitored target pages with baseline vs latest metrics", "parameters": [ { "name": "project_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "number", "default": 50, "maximum": 200 } } ], "responses": { "200": { "description": "OK" } } } }, "/traffic-analytics/pages/{id}/history": { "get": { "operationId": "getTrafficPageHistory", "tags": [ "Traffic Analytics" ], "summary": "Snapshot history for one monitored page", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "number", "default": 30, "maximum": 365 } } ], "responses": { "200": { "description": "OK" } } } }, "/projects/{id}/insights": { "get": { "operationId": "getSiteInsights", "tags": [ "Projects" ], "summary": "Site Insights roll-up for a project", "description": "Latest Backlink Intelligence run, live monitored backlinks, top traffic pages, tracked keywords, last site audit, AI insights and recent orders.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } } }, "/wishlist": { "get": { "operationId": "listWishlist", "tags": [ "Projects" ], "summary": "List saved publishers", "responses": { "200": { "description": "OK" } } }, "post": { "operationId": "addWishlist", "tags": [ "Projects" ], "summary": "Save a publisher to your wishlist", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "publisher_id" ], "properties": { "publisher_id": { "type": "string" }, "notes": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK" } } } }, "/wishlist/{id}": { "delete": { "operationId": "removeWishlist", "tags": [ "Projects" ], "summary": "Remove a publisher from your wishlist", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/saved-keyword-lists": { "get": { "operationId": "listSavedKeywordLists", "tags": [ "Projects" ], "summary": "List saved keyword lists", "responses": { "200": { "description": "OK" } } }, "post": { "operationId": "createSavedKeywordList", "tags": [ "Projects" ], "summary": "Create a keyword list", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "color": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK" } } } }, "/saved-keywords": { "get": { "operationId": "listSavedKeywords", "tags": [ "Projects" ], "summary": "List saved keywords", "parameters": [ { "name": "list_id", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "number" } } ], "responses": { "200": { "description": "OK" } } }, "post": { "operationId": "saveKeyword", "tags": [ "Projects" ], "summary": "Save a keyword", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "keyword" ], "properties": { "keyword": { "type": "string" }, "list_id": { "type": "string" }, "search_volume": { "type": "number" }, "cpc": { "type": "number" }, "competition_level": { "type": "string" }, "search_intent": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK" } } } }, "/projects": { "get": { "operationId": "listProjects", "tags": [ "Projects" ], "summary": "List your SEO projects", "responses": { "200": { "description": "OK" } } }, "post": { "operationId": "createProject", "tags": [ "Projects" ], "summary": "Create a project", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "niches": { "type": "array", "items": { "type": "string" } }, "keywords": { "type": "array", "items": { "type": "string" } }, "target_country": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK" } } } }, "/projects/{id}/summary": { "get": { "operationId": "getProjectSummary", "tags": [ "Projects" ], "summary": "Aggregated SEO summary for a project (recent KR jobs, audits, content, link insertions, gap runs)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/link-insertion/search": { "post": { "operationId": "linkInsertionSearch", "tags": [ "Analysis" ], "x-openai-isConsequential": true, "summary": "Search a publisher domain for articles matching a keyword (1 credit)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "publisher_domain", "keyword" ], "properties": { "publisher_domain": { "type": "string" }, "keyword": { "type": "string" }, "project_id": { "type": "string" }, "limit": { "type": "number" } } } } } }, "responses": { "200": { "description": "OK" }, "402": { "description": "Insufficient credits" } } } }, "/link-insertion/searches": { "get": { "operationId": "listLinkInsertionSearches", "tags": [ "Analysis" ], "summary": "List recent link insertion searches", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "number" } } ], "responses": { "200": { "description": "OK" } } } }, "/link-insertion/searches/{id}": { "get": { "operationId": "getLinkInsertionSearch", "tags": [ "Analysis" ], "summary": "Get one search with its discovered articles (with SEO metrics)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/keyword-research": { "get": { "operationId": "listKeywordResearchJobs", "tags": [ "Analysis" ], "summary": "List keyword research jobs", "responses": { "200": { "description": "OK" } } }, "post": { "operationId": "createKeywordResearchJob", "tags": [ "Analysis" ], "x-openai-isConsequential": true, "summary": "Create a keyword research job", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "seed_keywords" ], "properties": { "seed_keywords": { "type": "array", "items": { "type": "string" } }, "project_id": { "type": "string" }, "name": { "type": "string" }, "competitor_targets": { "type": "array", "items": { "type": "string" } }, "language_code": { "type": "string" }, "location_code": { "type": "number" } } } } } }, "responses": { "200": { "description": "Returns job_id" } } } }, "/keyword-research/{id}": { "get": { "operationId": "getKeywordResearchJob", "tags": [ "Analysis" ], "summary": "Get a keyword research job with its keywords, clusters, and competitors", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/keyword-research/{id}/expand": { "post": { "operationId": "expandKeywordResearchJob", "tags": [ "Analysis" ], "x-openai-isConsequential": true, "summary": "Trigger keyword expansion for a job (uses DataForSEO; charges credits)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/backlink-gap": { "get": { "operationId": "listBacklinkGap", "tags": [ "Analysis" ], "summary": "List backlink gap runs", "responses": { "200": { "description": "OK" } } }, "post": { "operationId": "startBacklinkGap", "tags": [ "Analysis" ], "x-openai-isConsequential": true, "summary": "Run a backlink gap analysis (charges credits)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "your_target", "competitors" ], "properties": { "your_target": { "type": "string" }, "competitors": { "type": "array", "items": { "type": "string" } }, "mode": { "type": "string", "enum": [ "domain", "url" ] }, "view": { "type": "string", "enum": [ "domains", "pages" ] }, "filters": { "type": "object" } } } } } }, "responses": { "200": { "description": "OK" }, "402": { "description": "Insufficient credits" } } } }, "/backlink-gap/{id}": { "get": { "operationId": "getBacklinkGap", "tags": [ "Analysis" ], "summary": "Get a backlink gap run", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/site-audits": { "get": { "operationId": "listSiteAudits", "tags": [ "Analysis" ], "summary": "List site audits", "responses": { "200": { "description": "OK" } } }, "post": { "operationId": "startSiteAudit", "tags": [ "Analysis" ], "x-openai-isConsequential": true, "summary": "Start a site audit (charges credits)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string" }, "max_pages": { "type": "number", "maximum": 500 } } } } } }, "responses": { "200": { "description": "Returns audit id" } } } }, "/site-audits/{id}": { "get": { "operationId": "getSiteAudit", "tags": [ "Analysis" ], "summary": "Get audit with pages and issues", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/content-pieces": { "get": { "operationId": "listContentPieces", "tags": [ "Content" ], "summary": "List Content Pro pieces", "parameters": [ { "name": "project_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } }, "post": { "operationId": "createContentPiece", "tags": [ "Content" ], "summary": "Create a Content Pro draft", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "primary_keyword" ], "properties": { "primary_keyword": { "type": "string" }, "project_id": { "type": "string" }, "audience": { "type": "string" }, "topic_notes": { "type": "string" }, "content_type": { "type": "string" }, "target_word_count": { "type": "number" }, "intent": { "type": "string" }, "secondary_keywords": { "type": "array", "items": { "type": "string" } }, "links": { "type": "array", "items": { "type": "object", "properties": { "anchor": { "type": "string" }, "url": { "type": "string" } } } } } } } } }, "responses": { "200": { "description": "OK" } } } }, "/content-pieces/{id}": { "get": { "operationId": "getContentPiece", "tags": [ "Content" ], "summary": "Get a content piece", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } }, "patch": { "operationId": "updateContentPiece", "tags": [ "Content" ], "summary": "Update brief, outline inputs, secondary keywords or link insertions", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "primary_keyword": { "type": "string" }, "topic_notes": { "type": "string" }, "audience": { "type": "string" }, "content_type": { "type": "string" }, "target_word_count": { "type": "number" }, "intent": { "type": "string" }, "url_slug": { "type": "string" }, "meta_title": { "type": "string" }, "meta_description": { "type": "string" }, "secondary_keywords": { "type": "array", "items": { "type": "string" } }, "links": { "type": "array", "items": { "type": "object", "properties": { "anchor": { "type": "string" }, "url": { "type": "string" } } } } } } } } }, "responses": { "200": { "description": "OK" } } } }, "/content-pro/keywords": { "post": { "operationId": "contentProKeywordFind", "tags": [ "Content" ], "summary": "Suggest primary keywords with volume and difficulty (free)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "seed" ], "properties": { "seed": { "type": "string" }, "project_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK" } } } }, "/content-pro/fanout-questions": { "post": { "operationId": "contentProFanoutQuestions", "tags": [ "Content" ], "summary": "Fan-out follow-up questions with volumes and intent (free)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "keyword" ], "properties": { "keyword": { "type": "string" }, "location_code": { "type": "number" }, "language_code": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK" } } } }, "/content-pieces/{id}/references": { "post": { "operationId": "contentProAddReference", "tags": [ "Content" ], "summary": "Attach a reference URL or pasted context to a piece", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/content-pieces/{id}/serp": { "post": { "operationId": "contentProSerpPreview", "tags": [ "Content" ], "summary": "Free SERP preview of ranking competitors", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/content-pieces/{id}/research": { "post": { "operationId": "contentProResearch", "tags": [ "Content" ], "summary": "Run competitor analysis, outline and statistics research (free)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "selected_competitor_urls": { "type": "array", "items": { "type": "string" } }, "skip_competitors": { "type": "boolean" }, "research_stats": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "OK" } } }, "get": { "operationId": "contentProGetResearch", "tags": [ "Content" ], "summary": "Get the latest research snapshot and outline", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/content-pieces/{id}/generate": { "post": { "operationId": "generateContent", "tags": [ "Content" ], "x-openai-isConsequential": true, "summary": "Generate a content piece (charges credits)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "outline_override": {}, "humanize": { "type": "boolean" }, "generate_images": { "type": "boolean" }, "image_style": { "type": "string" }, "cited_facts": { "type": "array", "items": { "type": "object" } } } } } } }, "responses": { "200": { "description": "OK" } } } }, "/content-pieces/{id}/draft": { "get": { "operationId": "contentProGetDraft", "tags": [ "Content" ], "summary": "Get the latest draft markdown, HTML, FAQ and schema", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/content-pieces/{id}/coverage": { "post": { "operationId": "contentProCoverage", "tags": [ "Content" ], "summary": "Check fan-out question coverage of the draft", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/content-pieces/{id}/revise": { "post": { "operationId": "contentProRevise", "tags": [ "Content" ], "x-openai-isConsequential": true, "summary": "Revise the draft (charges credits)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "goal": { "type": "string", "enum": [ "readability", "intent", "fluff", "custom" ] }, "instruction": { "type": "string" }, "search_intent": { "type": "string" }, "markdown": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK" } } } }, "/content-pieces/{id}/keywords/insert": { "post": { "operationId": "contentProInsertKeywords", "tags": [ "Content" ], "x-openai-isConsequential": true, "summary": "Weave additional keywords into the draft", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "keywords" ], "properties": { "keywords": { "type": "array", "items": { "type": "string" } }, "markdown": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK" } } } }, "/content-pieces/{id}/autolink": { "post": { "operationId": "contentProAutolink", "tags": [ "Content" ], "summary": "Suggest internal links for the draft", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/content-pieces/{id}/meta": { "post": { "operationId": "contentProSuggestMeta", "tags": [ "Content" ], "summary": "Suggest a meta title or description", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "meta_title", "meta_description" ] } } } } } }, "responses": { "200": { "description": "OK" } } } }, "/content-pieces/{id}/distribute": { "post": { "operationId": "contentProDistribute", "tags": [ "Content" ], "x-openai-isConsequential": true, "summary": "Create social and newsletter variants (charges credits)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/content-pieces/{id}/variants": { "get": { "operationId": "contentProListVariants", "tags": [ "Content" ], "summary": "List distribution variants for a piece", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/content-pro/variants/{id}/regenerate": { "post": { "operationId": "contentProRegenerateVariant", "tags": [ "Content" ], "x-openai-isConsequential": true, "summary": "Regenerate or edit one distribution variant", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/content-pro/assets": { "get": { "operationId": "contentProListAssets", "tags": [ "Content" ], "summary": "List linkable assets", "responses": { "200": { "description": "OK" } } }, "post": { "operationId": "contentProCreateAsset", "tags": [ "Content" ], "x-openai-isConsequential": true, "summary": "Create a linkable asset (calculator, chart, stat pack)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "asset_type", "topic" ], "properties": { "asset_type": { "type": "string" }, "topic": { "type": "string" }, "content_piece_id": { "type": "string" }, "brand_name": { "type": "string" }, "target_url": { "type": "string" }, "anchor_text": { "type": "string" }, "accent_color": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK" } } } }, "/content-pro/assets/{id}/recheck": { "post": { "operationId": "contentProRecheckAsset", "tags": [ "Content" ], "summary": "Re-verify an asset's sources", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/site-finder/search": { "post": { "operationId": "siteFinderSearch", "tags": [ "PR" ], "x-openai-isConsequential": true, "summary": "Site Finder web search for prospects", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string" }, "location_code": { "type": "number" }, "language_code": { "type": "string" }, "depth": { "type": "number" } } } } } }, "responses": { "200": { "description": "OK" } } } }, "/site-finder/searches": { "get": { "operationId": "listSiteFinderSearches", "tags": [ "PR" ], "summary": "List Site Finder searches", "responses": { "200": { "description": "OK" } } } }, "/site-finder/prospects": { "get": { "operationId": "listSiteFinderProspects", "tags": [ "PR" ], "summary": "List Site Finder prospects", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "number" } } ], "responses": { "200": { "description": "OK" } } } }, "/webhooks": { "get": { "operationId": "listWebhooks", "tags": [ "Webhooks" ], "summary": "List your webhook endpoints", "responses": { "200": { "description": "OK" } } }, "post": { "operationId": "createWebhook", "tags": [ "Webhooks" ], "summary": "Register a webhook endpoint (returns the signing_secret once)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "order.status_changed", "order.completed", "site_audit.completed", "pitch.replied", "*" ] } } } } } } }, "responses": { "200": { "description": "OK" } } } }, "/webhooks/{id}": { "delete": { "operationId": "deleteWebhook", "tags": [ "Webhooks" ], "summary": "Delete a webhook endpoint", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/webhooks/deliveries": { "get": { "operationId": "listWebhookDeliveries", "tags": [ "Webhooks" ], "summary": "List recent webhook delivery attempts", "parameters": [ { "name": "endpoint_id", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "number" } } ], "responses": { "200": { "description": "OK" } } } }, "/rank-tracker/keywords": { "get": { "operationId": "listRtKeywords", "tags": [ "Analysis" ], "summary": "List tracked keywords (Rank Tracker)", "parameters": [ { "name": "project_id", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "number" } } ], "responses": { "200": { "description": "OK" } } }, "post": { "operationId": "addRtKeyword", "tags": [ "Analysis" ], "summary": "Start tracking a keyword for a project", "responses": { "200": { "description": "OK" } } } }, "/rank-tracker/keywords/{id}": { "delete": { "operationId": "deleteRtKeyword", "tags": [ "Analysis" ], "summary": "Stop tracking a keyword", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/rank-tracker/keywords/{id}/history": { "get": { "operationId": "rtKeywordHistory", "tags": [ "Analysis" ], "summary": "Historical SERP positions for a tracked keyword", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "number" } } ], "responses": { "200": { "description": "OK" } } } }, "/rank-tracker/check": { "post": { "operationId": "rtCheck", "tags": [ "Analysis" ], "x-openai-isConsequential": true, "summary": "Refresh Google rankings for tracked keywords (1 credit/keyword)", "responses": { "200": { "description": "OK" } } } }, "/rank-tracker/competitors": { "get": { "operationId": "listRtCompetitors", "tags": [ "Analysis" ], "summary": "List rank-tracking competitors for a project", "parameters": [ { "name": "project_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } }, "post": { "operationId": "addRtCompetitor", "tags": [ "Analysis" ], "summary": "Add a competitor to track for a project", "responses": { "200": { "description": "OK" } } } }, "/rank-tracker/competitors/{id}": { "delete": { "operationId": "deleteRtCompetitor", "tags": [ "Analysis" ], "summary": "Remove a tracked competitor", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/ai-visibility/check": { "post": { "operationId": "aiVisibilityCheck", "tags": [ "Analysis" ], "x-openai-isConsequential": true, "summary": "Check ChatGPT/Perplexity/Google AIO mentions for tracked keywords (~1 credit/keyword)", "responses": { "200": { "description": "OK" } } } }, "/ai-visibility/mentions": { "get": { "operationId": "listAiMentions", "tags": [ "Analysis" ], "summary": "List recorded AI Visibility snapshots", "parameters": [ { "name": "project_id", "in": "query", "schema": { "type": "string" } }, { "name": "keyword_id", "in": "query", "schema": { "type": "string" } }, { "name": "llm_model", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "number" } } ], "responses": { "200": { "description": "OK" } } } }, "/ai-visibility/responses": { "get": { "operationId": "listAiResponses", "tags": [ "Analysis" ], "summary": "List captured AI responses with citations", "parameters": [ { "name": "project_id", "in": "query", "schema": { "type": "string" } }, { "name": "keyword_id", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "number" } } ], "responses": { "200": { "description": "OK" } } } }, "/backlink-analysis": { "post": { "operationId": "backlinkAnalysis", "tags": [ "Backlinks" ], "x-openai-isConsequential": true, "summary": "Backlink analysis (overview/refdomains/anchors/pages/history/ranked_keywords/etc.) via DataForSEO", "responses": { "200": { "description": "OK" } } } }, "/backlink-analysis/scans": { "get": { "operationId": "listBacklinkScans", "tags": [ "Backlinks" ], "summary": "List saved backlink scans", "responses": { "200": { "description": "OK" } } } }, "/gbp/businesses": { "get": { "operationId": "gbpListBusinesses", "tags": [ "GBP" ], "summary": "List tracked Google Business Profile locations", "responses": { "200": { "description": "OK" } } } }, "/gbp/keywords": { "get": { "operationId": "gbpListKeywords", "tags": [ "GBP" ], "summary": "List tracked GBP local-pack keywords", "parameters": [ { "name": "business_id", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "number" } } ], "responses": { "200": { "description": "OK" } } } }, "/gbp/check": { "post": { "operationId": "gbpCheck", "tags": [ "GBP" ], "x-openai-isConsequential": true, "summary": "Refresh GBP rankings for tracked keywords (1 credit each)", "responses": { "200": { "description": "OK" } } } }, "/pr-campaigns": { "get": { "operationId": "listPrCampaigns", "tags": [ "PR" ], "summary": "List PR Campaigner campaigns", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "number" } } ], "responses": { "200": { "description": "OK" } } } }, "/pr-campaigns/{id}": { "get": { "operationId": "getPrCampaign", "tags": [ "PR" ], "summary": "Get a PR Campaigner campaign", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/pr-campaigns/{id}/pitches": { "get": { "operationId": "listPrCampaignPitches", "tags": [ "PR" ], "summary": "List pitches inside a PR Campaigner campaign", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "number" } } ], "responses": { "200": { "description": "OK" } } } } } }