{ "openapi": "3.1.0", "info": { "title": "Conductor API Documentation", "version": "4.0.0", "license": { "name": "Conductor terms of service", "url": "https://www.conductor.com/legal/" }, "termsOfService": "https://www.conductor.com/legal/", "x-logo": { "url": "https://app.conductor.com/images/global/logo_login.png" } }, "servers": [ { "url": "https://api.conductor.com" } ], "security": [ { "ApiToken": [] }, { "ApiKeyQuery": [], "SigQuery": [] } ], "tags": [ { "name": "Draft Management", "description": "Create, retrieve, update, and delete Writing Assistant drafts." }, { "name": "Content Insights", "description": "Request and retrieve AI-driven content insights and recommendations for a draft." }, { "name": "Content Generation", "description": "Generate and revise content assets — outlines, drafts, meta descriptions, title tags, outline expansions, and shortened text." }, { "name": "Content Guidance", "description": "Validate and guide content against target keywords and optimization criteria." }, { "name": "Content Score", "description": "Evaluate on-page content and return scoring insights across intent alignment and topical coverage." }, { "name": "Content Profile", "description": "Create, retrieve, update, and delete reusable voice, tone, and language-rule profiles applied to draft generation." }, { "name": "Internal Linking", "description": "Get anchor text and URL recommendations for internal linking based on a customer's embedded pages." } ], "paths": { "/v4/accounts/{accountId}/drafts": { "post": { "tags": [ "Draft Management" ], "summary": "Create a draft", "operationId": "createDraft", "description": "Creates a new writing assistant draft. Use the \"Get SERP URLs\" endpoint to research and select the target keyword phrases and competitor URLs used to generate insights from for this draft.", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Account identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftCreateRequest" }, "example": { "draftTitle": "Ultimate Guide to Data Integration", "phrases": [ "data integration platform", "data integration tools", "financial data integration" ], "competitorUrls": [ "https://www.example.com/data-integration", "https://www.example.org/guides/data-integration-tools" ], "rankSourceId": 1 } } } }, "responses": { "201": { "description": "Draft created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WritingAssistantDraft" } } } }, "400": { "description": "Invalid draft parameters: fewer than the minimum required competitor URLs, phrase limit exceeded, or no phrases were provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpringBootErrorResponse" } } } }, "401": { "description": "Missing or invalid API key/signature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "The account's subscription does not permit this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpringBootErrorResponse" } } } }, "403": { "description": "Caller does not have access to this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpringBootErrorResponse" } } } } } }, "get": { "tags": [ "Draft Management" ], "summary": "List drafts", "operationId": "getDrafts", "description": "Retrieves all writing assistant drafts associated with the account.", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Account identifier" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20 }, "description": "Maximum number of drafts to return." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Number of drafts to skip before returning results." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "TO_DO", "IN_PROGRESS", "IN_REVIEW", "APPROVED", "PUBLISHED" ] }, "description": "Filter drafts by status." } ], "responses": { "200": { "description": "Paginated list of drafts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftListResponse" } } } }, "401": { "description": "Missing or invalid API key/signature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Caller does not have access to this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpringBootErrorResponse" } } } } } } }, "/v4/accounts/{accountId}/drafts/{draftId}": { "get": { "tags": [ "Draft Management" ], "summary": "Get a draft", "operationId": "getDraft", "description": "Fetches a specific writing assistant draft by its unique identifier.", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Account identifier" }, { "name": "draftId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Draft identifier" }, { "name": "versionId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Specific version of the draft to retrieve" } ], "responses": { "200": { "description": "Draft", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WritingAssistantDraft" } } } }, "401": { "description": "Missing or invalid API key/signature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Caller does not have access to this account, or the draft belongs to a different account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpringBootErrorResponse" } } } }, "404": { "description": "Draft not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpringBootErrorResponse" } } } } } }, "put": { "tags": [ "Draft Management" ], "summary": "Update a draft", "operationId": "updateDraft", "description": "Updates properties of a writing assistant draft.", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Account identifier" }, { "name": "draftId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Draft identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WritingAssistantDraftUpdateInput" }, "example": { "draftTitle": "Updated Draft", "phrases": [ "Updated phrases" ], "competitorUrls": [ "https://www.example.com/data-integration", "https://www.example.org/guides/data-integration-tools" ], "title": "Updated title", "metaDescription": "Updated meta description", "bodyCopy": "Updated body copy" } } } }, "responses": { "200": { "description": "Updated draft", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WritingAssistantDraft" } } } }, "400": { "description": "Invalid draft parameters: fewer than the minimum required competitor URLs, or phrase topic limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpringBootErrorResponse" } } } }, "401": { "description": "Missing or invalid API key/signature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "The account's subscription does not permit this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpringBootErrorResponse" } } } }, "403": { "description": "Caller does not have access to this account, or the draft belongs to a different account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpringBootErrorResponse" } } } }, "404": { "description": "Draft not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpringBootErrorResponse" } } } } } }, "delete": { "tags": [ "Draft Management" ], "summary": "Delete a draft", "operationId": "deleteDraft", "description": "Deletes a writing assistant draft and its persisted content.", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Account identifier" }, { "name": "draftId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Draft identifier" } ], "responses": { "204": { "description": "No Content" }, "401": { "description": "Missing or invalid API key/signature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Caller does not have access to this account, or the draft belongs to a different account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpringBootErrorResponse" } } } }, "404": { "description": "Draft not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpringBootErrorResponse" } } } } } } }, "/v4/accounts/{accountId}/drafts/{draftId}/content-generations": { "post": { "tags": [ "Content Generation" ], "summary": "Generate content", "operationId": "createContentGeneration", "description": "Generate content for a draft. The request body is a discriminated union on `mode`: `generate_draft`, `revise_draft`, `generate_content_outline`, `generate_meta_descriptions`, `generate_title_tags`, `expand_text`, or `shorten_text`.", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Account identifier" }, { "name": "draftId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Draft identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentGenerationRequest" }, "examples": { "generate_content_outline": { "summary": "Generate outline", "value": { "mode": "generate_content_outline", "additionalInstructions": "Create a detailed outline with at least 5 main sections, focusing on practical tips and product comparisons" } }, "generate_draft": { "summary": "Generate draft", "value": { "mode": "generate_draft", "voiceAndTone": "Friendly and informative", "audience": "Data engineers and technical decision-makers", "termsToExclude": [ "cheap", "low-quality" ], "termsToReplace": [ { "term": "expensive", "replacement": "premium" } ], "additionalInstructions": "Include implementation guides and platform comparisons with specific recommendations" } }, "revise_draft": { "summary": "Revise draft", "value": { "mode": "revise_draft", "content": "[Current article content here...]", "revisionInstructions": "Add more practical examples and move the benefits section earlier in the article", "voiceAndTone": "Expert but approachable", "audience": "Data engineers and analytics teams", "termsToExclude": [ "difficult", "complicated" ] } }, "generate_meta_descriptions": { "summary": "Generate meta descriptions", "value": { "mode": "generate_meta_descriptions", "bodyCopy": "Comprehensive guide to choosing the best data integration platform for your business, including feature comparisons, deployment options, and top vendor recommendations.", "suggestedMetaDescriptionsCount": 3, "minCharactersPerMetaDescription": 140, "maxCharactersPerMetaDescription": 160, "year": 2025, "keyword": "best data integration platform", "metaDescriptions": [ "Find the perfect data integration platform for your business with our expert buying guide." ] } }, "generate_title_tags": { "summary": "Generate title tags", "value": { "mode": "generate_title_tags", "keyword": "best data integration platform 2025", "maxCharacters": 60, "brandName": "DataGuide" } }, "expand_text": { "summary": "Expand text", "value": { "mode": "expand_text", "outline": "1. Introduction to Data Integration Approaches\n2. ETL vs ELT\n3. Choosing a Platform\n4. Implementation and Maintenance\n", "section": [ "2. ETL vs ELT" ], "minSentences": 5, "maxSentences": 7, "objective": "educate and inform readers", "audience": "data engineers and analytics teams", "primaryKeyword": "ETL vs ELT", "readabilityLevel": "8th grade", "additionalKeywords": [ "data pipelines", "data warehouse", "data transformation" ] } }, "shorten_text": { "summary": "Shorten text", "value": { "mode": "shorten_text", "text": "When selecting a data integration platform for your business, there are numerous factors to consider including connector coverage, scalability, data quality, reliability, and overall value for money. Cloud-native platforms remain the most popular choice due to their flexibility and ease of deployment.", "targetLength": 50, "preserveKeyPoints": true } } } } } }, "responses": { "200": { "description": "Generated content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentGenerationResponse" } } } }, "401": { "description": "Missing or invalid API key/signature, or an invalid or expired session token.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/FastApiDetailError" } ] } } } }, "422": { "description": "Unrecognized mode or prompt label, or the requested generation could not be produced.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FastApiDetailError" } } } } } } }, "/v4/accounts/{accountId}/drafts/{draftId}/insights": { "post": { "tags": [ "Content Insights" ], "summary": "Request content insights", "operationId": "requestInsights", "description": "Submit a request to generate content insights for a draft.", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Account identifier" }, { "name": "draftId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Draft identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentInsightsRequest" }, "example": { "insight": { "input": { "topic": { "phrases": [ "data integration" ], "rankSourceId": 1, "webPropertyId": 1, "competitorUrls": [ "https://www.example.com/data-integration", "https://www.example.org/guides/data-integration-tools", "https://www.example.net/data-integration-platform", "https://www.example.com/blog/etl-vs-elt", "https://www.example.org/data-pipelines" ] } }, "request": { "insights": [ "PAA_INSIGHT", "BODY_CONTENT_COMMON", "CONTENT_ANALYSIS_INSIGHT", "HTML_HEADING1_COMMON", "HTML_HEADING2_COMMON", "HTML_HEADING3_COMMON", "HTML_META_DESCRIPTION_COMMON", "HTML_TITLE_COMMON", "CONTENT_LENGTH_INSIGHT", "READABILITY_INSIGHT", "OBJECTIVE_INSIGHT", "AUDIENCE_INSIGHT", "JOURNEY_STAGE_INSIGHT", "CONTENT_TYPE_INSIGHT", "SUBTOPIC_INSIGHT", "OPPORTUNITIES_SNIPPET", "MSV_SNIPPET" ] } } } } } }, "responses": { "202": { "description": "Insights request accepted" }, "401": { "description": "Missing or invalid API key/signature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Caller does not have access to this account, or the draft belongs to a different account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpringBootErrorResponse" } } } }, "404": { "description": "Draft not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpringBootErrorResponse" } } } } } }, "get": { "tags": [ "Content Insights" ], "summary": "Get content insights", "operationId": "getInsights", "description": "Retrieve results of a previously submitted insight generation request.", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Account identifier" }, { "name": "draftId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Draft identifier" }, { "name": "insights", "in": "query", "required": false, "description": "Specific insight types to retrieve", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InsightType" } }, "style": "form", "explode": true } ], "responses": { "200": { "description": "Insights status and data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentInsightsResponse" } } } }, "401": { "description": "Missing or invalid API key/signature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Caller does not have access to this account, or the draft belongs to a different account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpringBootErrorResponse" } } } }, "404": { "description": "Draft not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpringBootErrorResponse" } } } } } }, "put": { "tags": [ "Content Insights" ], "summary": "Update an insight", "operationId": "updateInsight", "description": "Apply a change to a specific insight, identified by insightType in the request body.", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Account identifier" }, { "name": "draftId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Draft identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsightUpdateInput" }, "example": { "insightType": "BODY_CONTENT_COMMON", "changeType": "USER_ADDED", "changeValue": "new keyword" } } } }, "responses": { "200": { "description": "Insight updated", "content": { "application/json": { "schema": { "type": "boolean" } } } }, "401": { "description": "Missing or invalid API key/signature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Caller does not have access to this account, or the draft belongs to a different account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpringBootErrorResponse" } } } }, "404": { "description": "Draft not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpringBootErrorResponse" } } } } } } }, "/v4/accounts/{accountId}/drafts/{draftId}/validate": { "post": { "tags": [ "Content Guidance" ], "summary": "Validate content guidance", "operationId": "validateContentGuidance", "description": "Validate on-page content (title, meta description, body copy) against Content Guidance recommendations for a given request.", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Account identifier" }, { "name": "draftId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Draft identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "metaDescription": { "type": "string" }, "bodyCopy": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Insight" } }, "example": [ { "type": "CONTENT_ANALYSIS_INSIGHT", "errorCode": null, "errorMessage": null, "insightScore": null, "summary": null, "status": null, "insightPresent": true, "empty": false, "details": { "financial data integration": true, "data pipelines": false, "drag-and-drop": false, "key features": false, "analytics": true, "customer experiences": true, "real-time": true, "use cases": true, "enable": true, "data lake": false, "data sources": true, "ai-powered": false, "analytics-ready": true, "resource-intensive": false, "data quality": true, "data-driven": true, "data integration solution": true, "data integration tools": true, "integration": true, "data volumes": false, "data integration": true, "data silos": true, "data warehouse": false, "data integration patterns": true, "data management": true, "ai-driven": false, "end-to-end": true, "low-code": false, "platform": true, "database": false, "cloud-native": true, "cloud-based": true, "data ingestion": false, "api integrations": true, "data transformation": true, "pre-built connectors": true, "target system": true, "api-based": true, "subscription-based": true, "on-premises": true, "different sources": false, "data integration platform": true, "operational efficiency": true, "transformation": true, "integrate": true, "multiple sources": false, "up-to-date": true, "enterprise-grade": false, "no-code": false, "various sources": false } }, { "type": "HTML_HEADING1_COMMON", "errorCode": null, "errorMessage": null, "insightScore": null, "summary": null, "status": null, "insightPresent": true, "empty": false, "details": { "data integration platform": false, "data integration for banking": false, "financial data integration": true, "data integration": true } }, { "type": "HTML_HEADING2_COMMON", "errorCode": null, "errorMessage": null, "insightScore": null, "summary": null, "status": null, "insightPresent": true, "empty": false, "details": { "data integration use cases": false, "financial data integration": true, "benefits of data integration": false, "data integration tools": false } }, { "type": "HTML_HEADING3_COMMON", "errorCode": null, "errorMessage": null, "insightScore": null, "summary": null, "status": null, "insightPresent": true, "empty": false, "details": { "financial data integration solutions": false, "data integration challenges": false, "benefits of data integration": false, "data integration tools": false } } ] } } }, "400": { "description": "Malformed request body. Returns no response body." }, "401": { "description": "Missing or invalid API key/signature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v4/accounts/{accountId}/serp-urls": { "get": { "tags": [ "SERP Analysis" ], "summary": "Get SERP URLs", "operationId": "getSerpUrls", "description": "Retrieves SERP URLs for multiple queries. This is a pre-requisite for creating a draft. Use this endpoint to research and select the target keyword phrases and competitor URLs the draft is optimized for.", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Account identifier" }, { "name": "rankSourceId", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "ID of the rank source (search engine)" }, { "name": "queries", "in": "query", "required": true, "description": "List of search terms to analyze. Repeat the parameter to add more queries.", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "first", "in": "query", "required": false, "schema": { "type": "integer", "default": 10 }, "description": "Number of results to return per query" } ], "responses": { "200": { "description": "SERP results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerpBatchResponse" } } } }, "400": { "description": "Missing required query parameter: queries or rankSourceId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpringBootErrorResponse" } } } }, "401": { "description": "Missing or invalid API key/signature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v4/accounts/{accountId}/drafts/{draftId}/content-score": { "post": { "tags": [ "Content Score" ], "summary": "Generate Content Score", "operationId": "generateContentScore", "description": "Evaluate content (title, meta description, body copy) for a draft and return scoring insights across multiple dimensions.", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Account identifier" }, { "name": "draftId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Draft identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentScoreRequest" }, "example": { "title": "How to Improve Team Communication", "metaDescription": "A practical guide to better collaboration.", "bodyCopy": "Effective communication helps teams align and execute." } } } }, "responses": { "200": { "description": "Content score", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentScoreResponse" }, "example": { "overallScore": 67, "responseId": "6fvXaYjXAuXd_uMPg4fYwQQ", "intentAlignment": { "objectiveAssessment": { "detailedEvaluation": "The content provides a professional comparison of checking and savings accounts but lacks a structured head-to-head of daily-access features.", "summary": "Strong analogy and decision framework; needs more granular detail on physical access differences.", "shortSummary": "Add concrete debit/ATM access details and a direct feature comparison.", "overallObjectiveScore": 1, "improvementPriority": [ "Compare daily access features like debit cards and ATMs.", "List common best-use cases for each account type." ] }, "audienceAssessment": { "detailedEvaluation": "Addresses early-career adults well but omits popular features like savings buckets and round-ups.", "summary": "Clear, practical breakdown with a solid decision framework.", "shortSummary": "Integrate automation features to better serve the audience.", "overallAlignmentScore": 2, "improvementPriority": [ "Incorporate automated round-ups and savings buckets.", "Refine terminology to avoid alienating non-technical readers." ] }, "journeyStageAssessment": { "detailedEvaluation": "Serves the Awareness stage effectively but leans into Consideration-level vetting detail.", "summary": "Aligns well with Awareness by framing finance as a strategic system.", "shortSummary": "Solid Awareness content; focus more on lifestyle benefits.", "overallJourneyScore": 1, "improvementPriority": [ "Deepen the 'why' with lifestyle impacts before listing criteria.", "Emphasize emergency funds over technical vetting frameworks." ] }, "intentScore": 37 }, "topicalCoverage": { "questionsAssessment": { "questionEvaluations": [ { "question": "What is a savings account and how does it work?", "explanation": "Defines it as a Growth Layer that earns interest to protect against inflation.", "score": 1 }, { "question": "Does Thrivent have a savings account?", "explanation": "No mention of Thrivent or specific banking brands.", "score": 0 } ], "overallScore": 1, "summary": "High-quality strategic advice undermined by missing brand-specific answers.", "shortSummary": "Strong framework, missing specific brand information.", "improvementPriority": [ "Address specific providers like Thrivent and Schwab.", "Define how checking accounts relate to debit cards." ] }, "subtopicAssessment": { "subtopicEvaluations": [ { "subtopic": "What checking accounts are and how they work", "score": 1, "explanation": "Defines checking as an 'operating system' for paychecks and expenses." } ], "overallScore": 1, "summary": "Solid framework that needs more detail on account linking and overdraft protection.", "shortSummary": "Needs detail on direct deposits and overdraft protection.", "improvementPriority": [ "Detail setting up automated transfers and direct deposits.", "Explain how overdraft protection works between accounts." ] }, "keyTermsAssessment": null, "coverageScore": { "score": 1, "scoreMatches": [ { "term": "checking account", "termType": "IMPORTANT", "match": true }, { "term": "debit card", "termType": "IMPORTANT", "match": false }, { "term": "minimum balance", "termType": "SUPPORTING", "match": true }, { "term": "savings goals", "termType": "ADDITIONAL", "match": true } ] }, "topicalCoverageScore": 30 } } } } }, "401": { "description": "Missing or invalid API key/signature, or an invalid or expired session token.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/FastApiDetailError" } ] } } } }, "404": { "description": "Draft not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FastApiDetailError" } } } } } } }, "/v4/accounts/{accountId}/content-profiles": { "post": { "tags": [ "Content Profile" ], "summary": "Create content profile", "operationId": "createContentProfile", "description": "Creates a content profile for the account.", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Account identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentProfileInput" }, "example": { "name": "Brand Voice", "description": "Default brand voice profile", "voiceTone": "Confident and friendly", "audience": "Marketing managers", "languageRules": [ { "term": "utilize", "type": "EXCLUDE" } ] } } } }, "responses": { "201": { "description": "Created content profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentProfile" } } } }, "401": { "description": "Missing or invalid API key/signature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Caller does not have access to this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpringBootErrorResponse" } } } } } }, "get": { "tags": [ "Content Profile" ], "summary": "List content profiles", "operationId": "getContentProfiles", "description": "Returns all non-deleted content profiles for the account.", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Account identifier" } ], "responses": { "200": { "description": "Content profiles", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ContentProfile" } } } } }, "401": { "description": "Missing or invalid API key/signature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Caller does not have access to this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpringBootErrorResponse" } } } } } } }, "/v4/accounts/{accountId}/content-profiles/{contentProfileId}": { "get": { "tags": [ "Content Profile" ], "summary": "Get content profile", "operationId": "getContentProfile", "description": "Returns a single content profile by id.", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Account identifier" }, { "name": "contentProfileId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Content profile identifier" } ], "responses": { "200": { "description": "Content profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentProfile" } } } }, "401": { "description": "Missing or invalid API key/signature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Caller does not have access to this account, or the content profile belongs to a different account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpringBootErrorResponse" } } } }, "404": { "description": "Content profile not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpringBootErrorResponse" } } } } } }, "put": { "tags": [ "Content Profile" ], "summary": "Update content profile", "operationId": "updateContentProfile", "description": "Updates the properties of an existing content profile.", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Account identifier" }, { "name": "contentProfileId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Content profile identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentProfileInput" }, "example": { "name": "Updated Brand Voice", "description": "Updated description", "voiceTone": "Authoritative", "audience": "Executives", "languageRules": [ { "term": "cheap", "type": "EXCLUDE" } ] } } } }, "responses": { "200": { "description": "Updated content profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentProfile" } } } }, "401": { "description": "Missing or invalid API key/signature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Caller does not have access to this account, or the content profile belongs to a different account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpringBootErrorResponse" } } } }, "404": { "description": "Content profile not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpringBootErrorResponse" } } } } } }, "delete": { "tags": [ "Content Profile" ], "summary": "Delete content profile", "operationId": "deleteContentProfile", "description": "Soft-deletes a content profile so it no longer appears in listings.", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Account identifier" }, { "name": "contentProfileId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Content profile identifier" } ], "responses": { "204": { "description": "No Content" }, "401": { "description": "Missing or invalid API key/signature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Caller does not have access to this account, or the content profile belongs to a different account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpringBootErrorResponse" } } } }, "404": { "description": "Content profile not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpringBootErrorResponse" } } } } } } }, "/v4/accounts/{accountId}/internal-link-recommendations": { "post": { "tags": [ "Internal Linking" ], "summary": "Anchor text and URL recommendations", "operationId": "getInternalLinkRecommendations", "description": "Get anchor text and URL recommendations for a given block of text using the customer's embedded pages.", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Account identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalLinkRecommendationsInput" }, "example": { "text": "Looking for the best running shoes for marathons.", "webPropertyId": 456, "linkExclusionUrls": [ "https://www.example.com/discontinued-product" ] } } } }, "responses": { "200": { "description": "Anchor text and URL recommendations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnchorAndLinkResponse" } } } }, "401": { "description": "Missing or invalid API key/signature, or an invalid or expired session token.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/FastApiDetailError" } ] } } } }, "422": { "description": "A required field is missing or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FastApiValidationError" } } } }, "500": { "description": "Unexpected error, e.g. the account or web property could not be resolved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FastApiDetailError" } } } } } } } }, "components": { "securitySchemes": { "ApiKeyQuery": { "type": "apiKey", "in": "query", "name": "apiKey", "description": "API Key as a query parameter" }, "SigQuery": { "type": "apiKey", "in": "query", "name": "sig", "description": "Request signature computed using API key and secret. Valid for 5 minutes after creation." }, "ApiToken": { "type": "http", "scheme": "bearer", "description": "Conductor API token, sent as `Bearer `. Generate a token from Integrations > API > Create API Token." } }, "schemas": { "Error": { "type": "object", "description": "Error envelope for failures that apply uniformly across all v4 endpoints (e.g. gateway-level authentication failures).", "properties": { "code": { "type": "string", "description": "Machine-readable error code." }, "message": { "type": "string", "description": "Human-readable error description." } } }, "SpringBootErrorResponse": { "type": "object", "description": "Default error body returned by the Spring Boot backends (sage-history, content-guidance, serp-explorer) for unhandled/framework-level errors. Not endpoint-specific.", "properties": { "timestamp": { "type": "string", "format": "date-time" }, "status": { "type": "integer" }, "error": { "type": "string", "description": "HTTP reason phrase, e.g. \"Bad Request\"." }, "message": { "type": "string", "nullable": true, "description": "Often empty; these backends do not consistently populate a detail message." }, "path": { "type": "string" } } }, "FastApiDetailError": { "type": "object", "description": "Default error body returned by the FastAPI backends (content-generation, polaris-api, internal-linking-recommendations) for HTTPException-based errors.", "properties": { "detail": { "type": "string" } } }, "FastApiValidationError": { "type": "object", "description": "Default request-validation error body returned by the FastAPI backends when the request body fails schema validation.", "properties": { "detail": { "type": "array", "items": { "type": "object", "properties": { "loc": { "type": "array", "items": { "type": "string" } }, "msg": { "type": "string" }, "type": { "type": "string" } } } } } }, "DraftCreateRequest": { "type": "object", "required": [ "draftTitle", "rankSourceId" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Client-supplied draft identifier. If omitted, one is generated." }, "draftTitle": { "type": "string", "description": "Draft title. (Note: not your page's title tag)" }, "phrases": { "type": "array", "items": { "type": "string" }, "description": "Target keyword phrases the draft is optimized for." }, "page": { "type": "string", "description": "Existing page to optimize in your draft." }, "rankSourceId": { "type": "integer", "description": "Rank source identifier." }, "webPropertyId": { "type": "integer", "description": "Web property identifier." }, "title": { "type": "string" }, "metaDescription": { "type": "string" }, "bodyCopy": { "type": "string", "description": "The body copy / main text content of the draft." }, "competitorUrls": { "type": "array", "items": { "type": "string", "format": "uri" }, "description": "Competitor URLs used to generate insights from for this draft." }, "contentProfileId": { "type": "string", "format": "uuid", "description": "Content Profile identifier." }, "referenceDocumentIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Reference Document identifiers." } } }, "WritingAssistantDraftUpdateInput": { "type": "object", "description": "Fields that can be updated on a writing assistant draft.", "properties": { "draftTitle": { "type": "string", "description": "Draft title. (Note: not your page's title tag)" }, "phrases": { "type": "array", "items": { "type": "string" }, "description": "Target keyword phrases the draft is optimized for." }, "competitorUrls": { "type": "array", "items": { "type": "string", "format": "uri" }, "description": "Competitor URLs used to generate insights from for this draft." }, "title": { "type": "string" }, "metaDescription": { "type": "string" }, "bodyCopy": { "type": "string" }, "contentProfileId": { "type": "string", "format": "uuid", "description": "Content Profile identifier." }, "referenceDocumentIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Reference Document identifiers." }, "page": { "type": "string", "description": "Existing page to optimize in your draft." } } }, "DraftListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WritingAssistantDraftListItem" }, "description": "The page of drafts matching the request." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total number of drafts matching the request, across all pages." }, "offset": { "type": "integer", "description": "Number of drafts skipped before this page." }, "limit": { "type": "integer", "description": "Maximum number of drafts returned in this page." }, "hasMore": { "type": "boolean", "description": "Whether additional pages of drafts are available." } } } } }, "WritingAssistantDraftListItem": { "type": "object", "properties": { "accountId": { "type": "integer", "description": "Account identifier." }, "id": { "type": "string", "format": "uuid", "description": "Draft identifier", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "draftTitle": { "type": "string", "description": "Draft title. (Note: not your page's title tag)" }, "phrases": { "type": "array", "items": { "type": "string" }, "description": "Target keyword phrases the draft is optimized for." }, "page": { "type": "string", "description": "Existing page to optimize in your draft." }, "rankSourceId": { "type": "integer", "description": "Rank source identifier." }, "webPropertyId": { "type": "integer", "description": "Web property identifier." }, "versionId": { "type": "string", "description": "Identifier of the specific draft version." }, "created": { "type": "string", "format": "date-time", "description": "created timestamp", "example": "2026-06-28T23:19:03.026-04:00" }, "createdBy": { "type": "integer" }, "updated": { "type": "string", "format": "date-time", "description": "last updated timestamp", "example": "2026-06-28T23:19:03.026-04:00" }, "updatedBy": { "type": "integer", "description": "User id of the last user to make an update." }, "assignee": { "type": "integer", "description": "User id of the user assigned to this draft." }, "status": { "type": "string", "description": "Draft status.", "enum": [ "TO_DO", "IN_PROGRESS", "IN_REVIEW", "APPROVED", "PUBLISHED" ] }, "competitorUrls": { "type": "array", "items": { "type": "string" }, "description": "Competitor URLs used to generate insights from for this draft." }, "contentProfileId": { "type": "string", "format": "uuid", "description": "Content Profile identifier." } } }, "WritingAssistantDraft": { "type": "object", "properties": { "accountId": { "type": "integer", "description": "Account identifier." }, "id": { "type": "string", "format": "uuid", "description": "Draft identifier", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "draftTitle": { "type": "string", "description": "Draft title. (Note: not your page's title tag)" }, "phrases": { "type": "array", "items": { "type": "string" }, "description": "Target keyword phrases the draft is optimized for." }, "page": { "type": "string", "description": "Existing page to optimize in your draft." }, "rankSourceId": { "type": "integer", "description": "Rank source identifier." }, "webPropertyId": { "type": "integer", "description": "Web property identifier." }, "versionId": { "type": "string", "description": "Identifier of the specific draft version." }, "title": { "type": "string" }, "metaDescription": { "type": "string" }, "bodyCopy": { "type": "string", "description": "The body copy / main text content of the draft." }, "created": { "type": "string", "format": "date-time", "description": "created timestamp", "example": "2026-06-28T23:19:03.026-04:00" }, "createdBy": { "type": "integer" }, "updated": { "type": "string", "format": "date-time", "description": "last updated timestamp", "example": "2026-06-28T23:19:03.026-04:00" }, "updatedBy": { "type": "integer", "description": "User id of the last user to make an update." }, "assignee": { "type": "integer", "description": "User id of the user assigned to this draft." }, "status": { "type": "string", "description": "Draft status.", "enum": [ "TO_DO", "IN_PROGRESS", "IN_REVIEW", "APPROVED", "PUBLISHED" ] }, "competitorUrls": { "type": "array", "items": { "type": "string" }, "description": "Competitor URLs used to generate insights from for this draft." }, "contentProfileId": { "type": "string", "format": "uuid", "description": "Content Profile identifier." } } }, "InsightType": { "type": "string", "enum": [ "PAA_INSIGHT", "BODY_CONTENT_COMMON", "CONTENT_ANALYSIS_INSIGHT", "HTML_HEADING1_COMMON", "HTML_HEADING2_COMMON", "HTML_HEADING3_COMMON", "HTML_META_DESCRIPTION_COMMON", "HTML_TITLE_COMMON", "CONTENT_LENGTH_INSIGHT", "READABILITY_INSIGHT", "OBJECTIVE_INSIGHT", "AUDIENCE_INSIGHT", "JOURNEY_STAGE_INSIGHT", "CONTENT_TYPE_INSIGHT", "SUBTOPIC_INSIGHT", "OPPORTUNITIES_SNIPPET", "MSV_SNIPPET" ] }, "ContentInsightsRequest": { "type": "object", "properties": { "insight": { "type": "object", "properties": { "input": { "type": "object", "properties": { "topic": { "type": "object", "properties": { "phrases": { "type": "array", "items": { "type": "string" } }, "rankSourceId": { "type": "integer" }, "webPropertyId": { "type": "integer" }, "competitorUrls": { "type": "array", "items": { "type": "string", "format": "uri" } } } } } }, "request": { "type": "object", "properties": { "insights": { "type": "array", "items": { "$ref": "#/components/schemas/InsightType" } } } } } } } }, "ContentInsightsResponse": { "type": "object", "required": [ "status", "insightsStatus", "snippetsStatus", "results" ], "properties": { "startTime": { "type": "integer", "format": "int64", "description": "Epoch milliseconds when generation started." }, "status": { "$ref": "#/components/schemas/CollectionStatus" }, "insightsStatus": { "$ref": "#/components/schemas/CollectionStatus" }, "snippetsStatus": { "$ref": "#/components/schemas/CollectionStatus" }, "results": { "type": "object", "nullable": true, "description": "Null while status is PROCESSING; populated once generation completes.", "required": [ "insights", "snippets" ], "properties": { "insights": { "type": "array", "items": { "$ref": "#/components/schemas/Insight" } }, "snippets": { "type": "array", "items": { "$ref": "#/components/schemas/Snippet" } }, "contentProfile": { "$ref": "#/components/schemas/ContentProfile", "nullable": true }, "referenceDocuments": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/ReferenceDocument" } } } } } }, "ContentOutlineRequest": { "type": "object", "properties": { "additionalInstructions": { "type": "string", "description": "Specific instructions for outline generation" } } }, "ContentOutlineResponse": { "type": "object", "properties": { "outline": { "type": "string", "description": "Generated outline text" } } }, "DraftGenerationRequest": { "type": "object", "properties": { "voiceAndTone": { "type": "string" }, "audience": { "type": "string" }, "termsToExclude": { "type": "array", "items": { "type": "string" } }, "termsToReplace": { "type": "array", "items": { "type": "object", "properties": { "term": { "type": "string" }, "replacement": { "type": "string" } } } }, "additionalInstructions": { "type": "string" } } }, "ReviseDraftRequest": { "type": "object", "properties": { "content": { "type": "string" }, "revisionInstructions": { "type": "string" }, "voiceAndTone": { "type": "string" }, "audience": { "type": "string" }, "termsToExclude": { "type": "array", "items": { "type": "string" } } } }, "DraftGenerationResponse": { "type": "object", "properties": { "draft": { "type": "string", "description": "Generated or revised draft content" } } }, "MetaDescriptionRequest": { "type": "object", "properties": { "bodyCopy": { "type": "string" }, "suggestedMetaDescriptionsCount": { "type": "integer" }, "minCharactersPerMetaDescription": { "type": "integer" }, "maxCharactersPerMetaDescription": { "type": "integer" }, "year": { "type": "integer" }, "keyword": { "type": "string" }, "metaDescriptions": { "type": "array", "items": { "type": "string" } } } }, "MetaDescriptionResponse": { "type": "object", "properties": { "descriptions": { "type": "array", "items": { "type": "string" } } } }, "TitleTagRequest": { "type": "object", "properties": { "keyword": { "type": "string" }, "maxCharacters": { "type": "integer" }, "brandName": { "type": "string" } } }, "TitleTagResponse": { "type": "object", "properties": { "titles": { "type": "array", "items": { "type": "string" } } } }, "OutlineExpansionRequest": { "type": "object", "required": [ "outline", "section" ], "properties": { "outline": { "type": "string" }, "section": { "type": "array", "items": { "type": "string" } }, "minSentences": { "type": "integer", "description": "Minimum number of sentences for the expanded section." }, "maxSentences": { "type": "integer", "description": "Maximum number of sentences for the expanded section." }, "objective": { "type": "string" }, "audience": { "type": "string" }, "primaryKeyword": { "type": "string" }, "readabilityLevel": { "type": "string" }, "additionalKeywords": { "type": "array", "items": { "type": "string" } } } }, "OutlineExpansionResponse": { "type": "object", "properties": { "content": { "type": "string", "description": "Expanded content for the requested section" } } }, "TextShortenerRequest": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string" }, "targetLength": { "type": "integer" }, "preserveKeyPoints": { "type": "boolean" } } }, "TextShortenerResponse": { "type": "object", "properties": { "shortenedText": { "type": "string" } } }, "SerpBatchResponse": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "query": { "type": "string" }, "urls": { "type": "array", "items": { "type": "string", "format": "uri" } } } } } } }, "GenerateContentOutlineInput": { "allOf": [ { "type": "object", "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "generate_content_outline" ] } } }, { "$ref": "#/components/schemas/ContentOutlineRequest" } ] }, "ReviseDraftInput": { "allOf": [ { "type": "object", "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "revise_draft" ] } } }, { "$ref": "#/components/schemas/ReviseDraftRequest" } ] }, "GenerateMetaDescriptionsInput": { "allOf": [ { "type": "object", "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "generate_meta_descriptions" ] } } }, { "$ref": "#/components/schemas/MetaDescriptionRequest" } ] }, "GenerateTitleTagsInput": { "allOf": [ { "type": "object", "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "generate_title_tags" ] } } }, { "$ref": "#/components/schemas/TitleTagRequest" } ] }, "ExpandTextInput": { "allOf": [ { "type": "object", "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "expand_text" ] } } }, { "$ref": "#/components/schemas/OutlineExpansionRequest" } ] }, "ShortenTextInput": { "allOf": [ { "type": "object", "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "shorten_text" ] } } }, { "$ref": "#/components/schemas/TextShortenerRequest" } ] }, "ContentGenerationRequest": { "oneOf": [ { "$ref": "#/components/schemas/GenerateDraftInput" }, { "$ref": "#/components/schemas/ReviseDraftInput" }, { "$ref": "#/components/schemas/GenerateContentOutlineInput" }, { "$ref": "#/components/schemas/GenerateMetaDescriptionsInput" }, { "$ref": "#/components/schemas/GenerateTitleTagsInput" }, { "$ref": "#/components/schemas/ExpandTextInput" }, { "$ref": "#/components/schemas/ShortenTextInput" } ], "discriminator": { "propertyName": "mode", "mapping": { "generate_draft": "#/components/schemas/GenerateDraftInput", "revise_draft": "#/components/schemas/ReviseDraftInput", "generate_content_outline": "#/components/schemas/GenerateContentOutlineInput", "generate_meta_descriptions": "#/components/schemas/GenerateMetaDescriptionsInput", "generate_title_tags": "#/components/schemas/GenerateTitleTagsInput", "expand_text": "#/components/schemas/ExpandTextInput", "shorten_text": "#/components/schemas/ShortenTextInput" } } }, "ContentGenerationResponse": { "oneOf": [ { "$ref": "#/components/schemas/ContentOutlineResponse" }, { "$ref": "#/components/schemas/DraftGenerationResponse" }, { "$ref": "#/components/schemas/MetaDescriptionResponse" }, { "$ref": "#/components/schemas/TitleTagResponse" }, { "$ref": "#/components/schemas/OutlineExpansionResponse" }, { "$ref": "#/components/schemas/TextShortenerResponse" } ] }, "InsightUpdateInput": { "type": "object", "description": "Matches the GraphQL WritingAssistantInsightChangeInput.", "required": [ "insightType", "changeType", "changeValue" ], "properties": { "insightType": { "type": "string", "description": "Type of insight to change, e.g. BODY_CONTENT_COMMON, HTML_TITLE_COMMON, HTML_META_DESCRIPTION_COMMON." }, "changeType": { "type": "string", "enum": [ "USER_ADDED", "HIDDEN", "RESTORED" ], "description": "Type of change to apply to the insight." }, "changeValue": { "type": "string", "description": "Value associated with the change." } } }, "GenerateDraftInput": { "allOf": [ { "type": "object", "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "generate_draft" ] } } }, { "$ref": "#/components/schemas/DraftGenerationRequest" } ] }, "ContentScoreRequest": { "type": "object", "required": [ "title", "metaDescription", "bodyCopy" ], "properties": { "title": { "type": "string", "description": "The title associated with the content." }, "metaDescription": { "type": "string", "description": "The meta description associated with the content." }, "bodyCopy": { "type": "string", "description": "The text content to be evaluated." } } }, "AssessmentNarrative": { "type": "object", "properties": { "detailedEvaluation": { "type": "string", "description": "In-depth evaluation narrative." }, "summary": { "type": "string", "description": "Mid-length summary of the evaluation." }, "shortSummary": { "type": "string", "description": "Brief one-line summary." }, "improvementPriority": { "type": "array", "items": { "type": "string" }, "description": "Ordered list of suggested improvements." } } }, "ObjectiveAssessment": { "allOf": [ { "$ref": "#/components/schemas/AssessmentNarrative" }, { "type": "object", "properties": { "overallObjectiveScore": { "type": "integer", "description": "Score from 0 to 2 for objective fulfillment." } } } ] }, "AudienceAssessment": { "allOf": [ { "$ref": "#/components/schemas/AssessmentNarrative" }, { "type": "object", "properties": { "overallAlignmentScore": { "type": "integer", "description": "Score from 0 to 2 for audience alignment." } } } ] }, "JourneyStageAssessment": { "allOf": [ { "$ref": "#/components/schemas/AssessmentNarrative" }, { "type": "object", "properties": { "overallJourneyScore": { "type": "integer", "description": "Score from 0 to 2 for journey-stage fit." } } } ] }, "IntentAlignment": { "type": "object", "description": "Evaluates how well content aligns with the configured objective, audience, and journey stage.", "properties": { "objectiveAssessment": { "$ref": "#/components/schemas/ObjectiveAssessment" }, "audienceAssessment": { "$ref": "#/components/schemas/AudienceAssessment" }, "journeyStageAssessment": { "$ref": "#/components/schemas/JourneyStageAssessment" }, "intentScore": { "type": "integer", "description": "Composite intent alignment score (0-50)." } } }, "QuestionEvaluation": { "type": "object", "properties": { "question": { "type": "string" }, "explanation": { "type": "string" }, "score": { "type": "integer" } } }, "QuestionsAssessment": { "type": "object", "description": "Evaluation of how well the content addresses target questions.", "properties": { "questionEvaluations": { "type": "array", "items": { "$ref": "#/components/schemas/QuestionEvaluation" }, "description": "Per-question scoring." }, "overallScore": { "type": "integer", "description": "Aggregate questions coverage score (0-2)." }, "summary": { "type": "string" }, "shortSummary": { "type": "string" }, "improvementPriority": { "type": "array", "items": { "type": "string" } } } }, "SubtopicEvaluation": { "type": "object", "properties": { "subtopic": { "type": "string" }, "score": { "type": "integer" }, "explanation": { "type": "string" } } }, "SubtopicAssessment": { "type": "object", "description": "Evaluation of subtopic coverage.", "properties": { "subtopicEvaluations": { "type": "array", "items": { "$ref": "#/components/schemas/SubtopicEvaluation" }, "description": "Per-subtopic scoring." }, "overallScore": { "type": "integer", "description": "Aggregate subtopic coverage score (0-2)." }, "summary": { "type": "string" }, "shortSummary": { "type": "string" }, "improvementPriority": { "type": "array", "items": { "type": "string" } } } }, "TermMatch": { "type": "object", "properties": { "term": { "type": "string" }, "termType": { "type": "string", "enum": [ "IMPORTANT", "SUPPORTING", "ADDITIONAL" ] }, "match": { "type": "boolean" } } }, "CoverageScore": { "type": "object", "description": "Term-level coverage breakdown.", "properties": { "score": { "type": "integer", "description": "Aggregate coverage score (0-2)." }, "scoreMatches": { "type": "array", "items": { "$ref": "#/components/schemas/TermMatch" }, "description": "Per-term match results." } } }, "TopicalCoverage": { "type": "object", "description": "Evaluates how thoroughly the content covers relevant questions, subtopics, and key terms.", "properties": { "questionsAssessment": { "$ref": "#/components/schemas/QuestionsAssessment" }, "subtopicAssessment": { "$ref": "#/components/schemas/SubtopicAssessment" }, "keyTermsAssessment": { "type": "object", "nullable": true, "description": "Key-terms assessment (may be null)." }, "coverageScore": { "$ref": "#/components/schemas/CoverageScore" }, "topicalCoverageScore": { "type": "integer", "description": "Composite topical coverage score (0-50)." } } }, "ContentScoreResponse": { "type": "object", "properties": { "overallScore": { "type": "integer", "description": "Score from 0 to 100." }, "responseId": { "type": "string", "description": "Identifier for the request." }, "intentAlignment": { "$ref": "#/components/schemas/IntentAlignment" }, "topicalCoverage": { "$ref": "#/components/schemas/TopicalCoverage" } } }, "AccountRef": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "integer", "description": "Account ID." } } }, "AudienceInsight": { "allOf": [ { "$ref": "#/components/schemas/Insight" }, { "type": "object", "properties": { "details": { "type": "object", "properties": { "audience": { "type": "string" } } } } } ] }, "ChangeType": { "type": "string", "nullable": true, "description": "User-applied change to an insight item. Null when untouched.", "enum": [ "USER_ADDED", "HIDDEN", "RESTORED" ] }, "CollectionStatus": { "type": "string", "description": "Collection/processing state for the response, an insight, a snippet, or a page.", "enum": [ "PROCESSING", "COMPLETED", "COMPLETED_WITH_ERROR", "FAILED", "TIMEOUTED" ] }, "ContentAnalysisInsight": { "allOf": [ { "$ref": "#/components/schemas/Insight" }, { "type": "object", "properties": { "details": { "type": "object", "properties": { "keywords": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/KeywordItem" } }, "maxOccurrence": { "type": "integer" }, "presets": { "type": "array", "items": { "type": "string" } } } }, "serp": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "pageMeta": { "$ref": "#/components/schemas/PageMeta" }, "keywords": { "type": "array", "items": { "type": "object", "properties": { "keyword": { "type": "string" }, "frequency": { "type": "integer" }, "otherKeywords": { "type": "array", "items": { "type": "string" } } } } } } } } } } } } } } ] }, "ContentLengthInsight": { "allOf": [ { "$ref": "#/components/schemas/Insight" }, { "type": "object", "properties": { "details": { "type": "object", "properties": { "serp": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "pageMeta": { "$ref": "#/components/schemas/PageMeta" }, "metricValue": { "type": "integer", "description": "Word count." } } } }, "topPageMetricValue": { "type": "integer" }, "averageMetricValue": { "type": "number" } } }, "whyImportantMessage": { "type": "string" }, "range": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "integer" } } } } } } } } ] }, "ContentProfile": { "type": "object", "required": [ "id", "accountId", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "accountId": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "voiceTone": { "type": "string", "nullable": true, "description": "Freeform voice-and-tone guidance applied to generation." }, "audience": { "type": "string", "nullable": true, "description": "Freeform target-audience description." }, "createdBy": { "type": "integer", "description": "User ID of the creator." }, "created": { "type": "string", "format": "date-time" }, "updatedBy": { "type": "integer" }, "updated": { "type": "string", "format": "date-time" }, "draftCount": { "type": "integer" }, "languageRules": { "type": "array", "items": { "$ref": "#/components/schemas/LanguageRule" } } } }, "ContentProfileInput": { "type": "object", "description": "Fields for creating or updating a content profile.", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "voiceTone": { "type": "string", "description": "Freeform voice-and-tone guidance applied to generation." }, "audience": { "type": "string", "description": "Freeform target-audience description." }, "languageRules": { "type": "array", "items": { "$ref": "#/components/schemas/LanguageRule" } } } }, "ContentTypeInsight": { "allOf": [ { "$ref": "#/components/schemas/Insight" }, { "type": "object", "properties": { "details": { "type": "object", "properties": { "contentType": { "type": "string" }, "contentTypes": { "type": "array", "items": { "type": "string" } } } } } } ] }, "HtmlFeature": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "metaDescription", "h1", "h2", "h3", "title" ] }, "xpath": { "type": "string" }, "innerText": { "$ref": "#/components/schemas/HtmlTemplatedString" }, "attributes": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/HtmlTemplatedString" } } } }, "HtmlFeatureValue": { "type": "object", "properties": { "template": { "type": "string" }, "xpath": { "type": "string" }, "value": { "type": "string" } } }, "HtmlKeywordSerpInsight": { "allOf": [ { "$ref": "#/components/schemas/Insight" }, { "type": "object", "properties": { "details": { "type": "object", "description": "Shared shape for HTML_TITLE_COMMON, HTML_META_DESCRIPTION_COMMON, HTML_HEADING1/2/3_COMMON, and BODY_CONTENT_COMMON.", "properties": { "keywords": { "type": "object", "properties": { "numOfSerps": { "type": "integer" }, "items": { "type": "array", "items": { "type": "object", "properties": { "keyword": { "type": "string" }, "numOfOccurrence": { "type": "integer" }, "ownMatched": { "type": "boolean" }, "changeType": { "$ref": "#/components/schemas/ChangeType" } } } } } }, "serp": { "type": "array", "items": { "$ref": "#/components/schemas/HtmlSerpPage" } } } } } } ] }, "HtmlSerpPage": { "type": "object", "properties": { "favicon": { "type": "string", "nullable": true }, "rank": { "type": "integer" }, "url": { "type": "string", "format": "uri" }, "status": { "$ref": "#/components/schemas/PageStatus" }, "title": { "$ref": "#/components/schemas/HtmlFeatureValue", "nullable": true }, "features": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/HtmlFeature" } } } }, "HtmlTemplatedString": { "type": "object", "properties": { "template": { "type": "string" }, "value": { "type": "string" } } }, "Insight": { "type": "object", "required": [ "type", "status", "insightPresent", "empty" ], "discriminator": { "propertyName": "type", "mapping": { "CONTENT_ANALYSIS_INSIGHT": "#/components/schemas/ContentAnalysisInsight", "PAA_INSIGHT": "#/components/schemas/PaaInsight", "READABILITY_INSIGHT": "#/components/schemas/ReadabilityInsight", "JOURNEY_STAGE_INSIGHT": "#/components/schemas/JourneyStageInsight", "SUBTOPIC_INSIGHT": "#/components/schemas/SubtopicInsight", "AUDIENCE_INSIGHT": "#/components/schemas/AudienceInsight", "OBJECTIVE_INSIGHT": "#/components/schemas/ObjectiveInsight", "CONTENT_TYPE_INSIGHT": "#/components/schemas/ContentTypeInsight", "CONTENT_LENGTH_INSIGHT": "#/components/schemas/ContentLengthInsight", "HTML_TITLE_COMMON": "#/components/schemas/HtmlKeywordSerpInsight", "HTML_META_DESCRIPTION_COMMON": "#/components/schemas/HtmlKeywordSerpInsight", "HTML_HEADING1_COMMON": "#/components/schemas/HtmlKeywordSerpInsight", "HTML_HEADING2_COMMON": "#/components/schemas/HtmlKeywordSerpInsight", "HTML_HEADING3_COMMON": "#/components/schemas/HtmlKeywordSerpInsight", "BODY_CONTENT_COMMON": "#/components/schemas/HtmlKeywordSerpInsight" } }, "properties": { "type": { "$ref": "#/components/schemas/InsightType" }, "errorCode": { "type": "string", "nullable": true }, "errorMessage": { "type": "string", "nullable": true }, "status": { "$ref": "#/components/schemas/ItemStatus" }, "summary": { "$ref": "#/components/schemas/InsightSummary", "nullable": true }, "insightPresent": { "type": "boolean" }, "empty": { "type": "boolean" }, "details": { "type": "object", "description": "Shape varies by insight type; see the concrete *Insight subtypes." } } }, "InsightSummary": { "type": "object", "properties": { "note": { "type": "string", "nullable": true }, "text": { "type": "string", "nullable": true } } }, "JourneyStageInsight": { "allOf": [ { "$ref": "#/components/schemas/Insight" }, { "type": "object", "properties": { "details": { "type": "object", "properties": { "journeyStage": { "type": "string" }, "journeyStages": { "type": "array", "items": { "type": "string" } } } } } } ] }, "KeywordItem": { "type": "object", "properties": { "keyword": { "type": "string" }, "numOfOccurrence": { "type": "integer" }, "avgFrequency": { "type": "integer" }, "topPageFrequency": { "type": "integer", "nullable": true }, "ownFrequency": { "type": "integer", "nullable": true }, "presets": { "type": "array", "items": { "type": "string", "enum": [ "IMPORTANT", "SUPPORTING", "ADDITIONAL" ] } }, "otherKeywords": { "type": "array", "nullable": true, "items": { "type": "string" } }, "changeType": { "$ref": "#/components/schemas/ChangeType" } } }, "LanguageRule": { "type": "object", "required": [ "term", "type" ], "properties": { "term": { "type": "string" }, "type": { "type": "string", "enum": [ "EXCLUDE" ], "description": "The rule to apply to term." }, "extraTerm": { "type": "string", "nullable": true, "description": "Reserved for future language-rule types." } } }, "InternalLinkFilter": { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "CONTAINS", "NOT_CONTAINS", "STARTS_WITH", "ENDS_WITH", "EXACT_MATCH", "IS_IN_PAGE_GROUP" ], "nullable": true, "description": "The operator used to filter candidate pages." }, "urlPattern": { "type": "string", "nullable": true, "description": "URL pattern used for filtering, applied per operator." }, "pageGroupIds": { "type": "array", "items": { "type": "integer" }, "nullable": true, "description": "Page group IDs used for filtering when operator is IS_IN_PAGE_GROUP." } } }, "InternalLinkRecommendationsInput": { "type": "object", "required": [ "text", "webPropertyId" ], "properties": { "text": { "type": "string", "description": "The text to analyze for internal link recommendations." }, "webPropertyId": { "type": "integer", "description": "Web property ID used to scope recommendations." }, "instructions": { "type": "string", "nullable": true, "description": "Optional instructions for the recommendations." }, "linkExclusionUrls": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "URLs to exclude from the recommendations." }, "linkFilter": { "allOf": [ { "$ref": "#/components/schemas/InternalLinkFilter" } ], "nullable": true, "description": "Filter narrowing which candidate pages are eligible for recommendations." }, "cache": { "type": "boolean", "default": false, "description": "Whether cached results may be used." }, "promptLabel": { "type": "string", "nullable": true, "description": "Prompt label used for recommendation generation." }, "language": { "type": "string", "nullable": true, "description": "Language filter for the recommendations." } } }, "AnchorTextAndUrl": { "type": "object", "required": [ "anchorText", "context", "url", "reason" ], "properties": { "anchorText": { "type": "string", "description": "The anchor text." }, "context": { "type": "string", "description": "The surrounding text where the anchor text is located." }, "url": { "type": "string", "description": "The URL recommended for the anchor text." }, "title": { "type": "string", "nullable": true, "description": "The title of the recommended link." }, "reason": { "type": "string", "description": "The reason for the recommendation." }, "chatCompletionId": { "type": "string", "nullable": true, "description": "The chat completion ID." } } }, "InternalLinkAdditionalInfo": { "type": "object", "properties": { "emptyResultsReason": { "type": "string", "nullable": true, "enum": [ "collection_not_found", "empty_vector_search", "llm_rejection", "llm_evaluation", "exclusion_list", "llm_rejection_and_exclusion_list" ], "description": "The reason for empty results, if any." }, "llmRejectedUrls": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "The URLs rejected by the LLM." }, "excludedUrls": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "The URLs excluded from the recommendations by the exclusion list." } } }, "AnchorAndLinkResponse": { "type": "object", "required": [ "anchorsAndUrls", "additionalInfo" ], "properties": { "anchorsAndUrls": { "type": "array", "items": { "$ref": "#/components/schemas/AnchorTextAndUrl" }, "description": "The anchor text and URL recommendations." }, "chatCompletionId": { "type": "string", "nullable": true, "description": "The chat completion ID." }, "additionalInfo": { "type": "array", "items": { "$ref": "#/components/schemas/InternalLinkAdditionalInfo" }, "description": "Additional information for the query." } } }, "MsvSnippet": { "allOf": [ { "$ref": "#/components/schemas/Snippet" }, { "type": "object", "properties": { "details": { "type": "object", "properties": { "rootKeyword": { "type": "string" }, "topicSearchVolume": { "type": "integer" }, "topicPhrase": { "type": "string" } } }, "phraseDetails": { "type": "array", "items": { "$ref": "#/components/schemas/PhraseVolume" } } } } ] }, "ObjectiveInsight": { "allOf": [ { "$ref": "#/components/schemas/Insight" }, { "type": "object", "properties": { "details": { "type": "object", "properties": { "objective": { "type": "string" } } } } } ] }, "OpportunitiesSnippet": { "allOf": [ { "$ref": "#/components/schemas/Snippet" }, { "type": "object", "properties": { "details": { "type": "object", "properties": { "phrase": { "type": "string", "nullable": true }, "topUrls": { "type": "array", "items": { "$ref": "#/components/schemas/OpportunityRank" } }, "ownPage": { "$ref": "#/components/schemas/OpportunityRank", "nullable": true, "description": "The account's own ranking page, or null when not ranking." } } } } } ] }, "OpportunityRank": { "type": "object", "required": [ "rank", "traffic" ], "properties": { "rank": { "type": "integer" }, "traffic": { "type": "integer", "description": "Estimated monthly organic traffic for the page at this rank." } } }, "PaaInsight": { "allOf": [ { "$ref": "#/components/schemas/Insight" }, { "type": "object", "properties": { "details": { "type": "object", "properties": { "paaQuestions": { "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string" }, "response": { "type": "string", "nullable": true }, "changeType": { "$ref": "#/components/schemas/ChangeType" } } } }, "whyImportantMessage": { "type": "string" } } } } } ] }, "PageMeta": { "type": "object", "properties": { "rank": { "type": "integer" }, "url": { "type": "string", "format": "uri" }, "favicon": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "collected": { "type": "boolean" } } }, "PhraseVolume": { "type": "object", "properties": { "rootKeyword": { "type": "string" }, "topicSearchVolume": { "type": "integer" }, "topicPhrase": { "type": "string" } } }, "ReadabilityInsight": { "allOf": [ { "$ref": "#/components/schemas/Insight" }, { "type": "object", "properties": { "details": { "type": "object", "properties": { "serp": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "pageMeta": { "$ref": "#/components/schemas/PageMeta" }, "metricValue": { "$ref": "#/components/schemas/ReadabilityMetric" } } } }, "topPageMetricValue": { "$ref": "#/components/schemas/ReadabilityMetric" }, "averageMetricValue": { "$ref": "#/components/schemas/ReadabilityMetric" } } }, "own": { "type": "object", "nullable": true }, "userDefinedTarget": { "type": "object", "nullable": true }, "whyImportantMessage": { "type": "string" } } } } } ] }, "ReadabilityMetric": { "type": "object", "properties": { "score": { "type": "number" }, "label": { "type": "string" }, "description": { "type": "string" }, "marker": { "type": "string", "enum": [ "LOWER", "EQUAL", "HIGHER" ] } } }, "ReferenceDocument": { "type": "object", "required": [ "id", "kind", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "TEXT", "FILE" ], "description": "TEXT for inline-supplied text (fileName null); FILE for an uploaded document (fileName populated)." }, "fileName": { "type": "string", "nullable": true, "description": "Original filename for FILE documents; null for TEXT." }, "text": { "type": "string", "nullable": true, "description": "Extracted or supplied text content." }, "status": { "type": "string", "enum": [ "EXTRACTED", "STORED", "ERROR" ] }, "createdBy": { "$ref": "#/components/schemas/UserRef" }, "created": { "type": "integer", "format": "int64", "description": "Epoch seconds." }, "account": { "$ref": "#/components/schemas/AccountRef" } } }, "Snippet": { "type": "object", "required": [ "type", "status" ], "discriminator": { "propertyName": "type", "mapping": { "MSV_SNIPPET": "#/components/schemas/MsvSnippet", "OPPORTUNITIES_SNIPPET": "#/components/schemas/OpportunitiesSnippet" } }, "properties": { "type": { "type": "string", "enum": [ "MSV_SNIPPET", "OPPORTUNITIES_SNIPPET" ] }, "status": { "$ref": "#/components/schemas/ItemStatus" }, "creationTime": { "type": "integer", "format": "int64", "nullable": true }, "errorCode": { "type": "string", "nullable": true }, "errorMessage": { "type": "string", "nullable": true }, "errorPhrases": { "type": "array", "items": { "type": "string" } } } }, "SubtopicInsight": { "allOf": [ { "$ref": "#/components/schemas/Insight" }, { "type": "object", "properties": { "details": { "type": "object", "properties": { "chatResponseId": { "type": "string" }, "subtopics": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "changeType": { "$ref": "#/components/schemas/ChangeType" } } } } } } } } ] }, "UserRef": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "integer", "description": "User ID." } } }, "ItemStatus": { "type": "string", "description": "Processing status for an individual insight or snippet item.", "enum": [ "COMPLETED", "COMPLETED_WITH_ERRORS", "ERROR" ] }, "PageStatus": { "type": "string", "description": "Collection status for an HTML SERP page.", "enum": [ "COLLECTED", "ERROR" ] } } } }