{ "openapi": "3.1.0", "info": { "title": "Frase API", "version": "1.0.0", "description": "The Frase API provides programmatic access to your SEO content platform. Use it to manage content, research, audits, AI visibility tracking, and more.\n\n## Authentication\n\nAll API requests require authentication using an API key. Include your key in the `X-API-KEY` header:\n\n```\nX-API-KEY: sk_live_your_api_key_here\n```\n\nFor legacy compatibility, the `token` header is also supported.\n\n## Rate Limits\n\nRate limits vary by plan. Rate limit headers are included in all responses:\n- `X-RateLimit-Limit`: Maximum requests per window\n- `X-RateLimit-Remaining`: Requests remaining\n- `X-RateLimit-Reset`: Reset timestamp\n\n## Errors\n\nThe API uses standard HTTP status codes and returns errors in a consistent format:\n\n```json\n{\n \"error\": {\n \"type\": \"authentication_error\",\n \"code\": \"invalid_api_key\",\n \"message\": \"Invalid API key provided.\",\n \"doc_url\": \"https://docs.frase.io/api/errors#invalid_api_key\"\n }\n}\n```", "contact": { "name": "Frase Support", "url": "https://frase.io", "email": "support@frase.io" }, "license": { "name": "Proprietary", "url": "https://www.frase.io/company/terms" } }, "servers": [ { "url": "https://next.frase.io/api/v1", "description": "Production" }, { "url": "http://localhost:3000/api/v1", "description": "Local Development" } ], "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "Content", "description": "Manage generated content articles" }, { "name": "Briefs", "description": "Content briefs and outlines" }, { "name": "Research", "description": "AI-powered research" }, { "name": "Audits", "description": "Site audits and SEO analysis" }, { "name": "Sites", "description": "Manage websites" }, { "name": "AI Visibility", "description": "Track brand visibility across AI platforms" }, { "name": "Analytics", "description": "Google Search Console and performance data" }, { "name": "SERP", "description": "SERP analysis and competitor research" }, { "name": "Optimizations", "description": "Content optimization suggestions" }, { "name": "Webhooks", "description": "Webhook subscriptions for event notifications" }, { "name": "Jobs", "description": "Async job status tracking" }, { "name": "Competitive Analysis", "description": "Competitive page analysis and gap identification" }, { "name": "Legacy", "description": "Legacy API endpoints for backward compatibility" }, { "name": "Rules", "description": "Content rules for automated quality checks" }, { "name": "Playbooks", "description": "Content playbooks for structured content workflows" }, { "name": "Rule Sets", "description": "Manage content rule sets for automated content evaluation" }, { "name": "Templates", "description": "Content templates for standardized outlines and formatting" }, { "name": "CMS", "description": "Frase CMS post management and bulk import" } ], "paths": { "/sites": { "get": { "operationId": "listSites", "summary": "List sites", "description": "Retrieve all websites associated with your organization.", "tags": [ "Sites" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } } ], "responses": { "200": { "description": "List of sites", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedSites" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "createSite", "summary": "Create site", "description": "Create a new website to track and manage content for.", "tags": [ "Sites" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSiteInput" } } } }, "responses": { "201": { "description": "Site created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteCreated" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/content": { "get": { "operationId": "listContent", "summary": "List content", "description": "Retrieve all content articles in your organization.", "tags": [ "Content" ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "draft", "generating", "review", "published", "archived" ] } }, { "name": "site_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "is_monitored", "in": "query", "description": "Filter by Content Guard monitoring state. 'true' returns only guarded articles, 'false' returns only un-guarded. Omit for no filter.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "List of content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedContent" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/content/generate": { "post": { "operationId": "generateContent", "summary": "Generate content from brief", "description": "Generate content from an existing brief. The brief must have a complete outline. The content generation runs asynchronously - use the returned content ID with the jobs endpoint to track progress.", "tags": [ "Content" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "brief_id" ], "properties": { "brief_id": { "type": "string", "format": "uuid", "description": "ID of the brief to generate content from. The brief must have a non-empty outline." }, "generate_images": { "type": "boolean", "default": false, "description": "Generate a hero image for the content. Uses hero image credits." } } } } } }, "responses": { "201": { "description": "Content generation started", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Content ID" }, "brief_id": { "type": "string", "format": "uuid", "description": "Brief ID" }, "title": { "type": "string", "description": "Content title (from brief topic)" }, "status": { "type": "string", "enum": [ "generating" ], "description": "Content status" }, "created_at": { "type": "string", "format": "date-time" }, "content_url": { "type": "string", "description": "URL to view the content in the Frase app" }, "status_url": { "type": "string", "description": "URL to check generation status" } } }, "request_id": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Brief not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (article or hero image limit)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "example": "rate_limit_error" }, "code": { "type": "string", "enum": [ "article_limit_exceeded", "hero_image_limit_exceeded" ] }, "message": { "type": "string" }, "doc_url": { "type": "string" } } } } } } } } } } }, "/content/{id}": { "get": { "operationId": "getContent", "summary": "Get content", "description": "Retrieve a specific content article by ID.", "tags": [ "Content" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Content details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Content" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "operationId": "updateContent", "summary": "Update content", "description": "Update content title, body, or metadata.", "tags": [ "Content" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "body": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "review", "published", "archived" ] }, "meta_title": { "type": "string" }, "meta_description": { "type": "string" } } } } } }, "responses": { "200": { "description": "Content updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "status": { "type": "string" }, "word_count": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" } } }, "request_id": { "type": "string" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "operationId": "deleteContent", "summary": "Delete content", "description": "Soft delete content (moves to trash).", "tags": [ "Content" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Content deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" } } }, "request_id": { "type": "string" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/content/{id}/status": { "get": { "operationId": "getContentStatus", "summary": "Get content generation status", "description": "Check the status of content generation.", "tags": [ "Content" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Content status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentStatus" } } } } } } }, "/content/{id}/export": { "get": { "operationId": "exportContent", "summary": "Export content", "description": "Export content in various formats.", "tags": [ "Content" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "html", "markdown" ], "default": "json" } } ], "responses": { "200": { "description": "Exported content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentExport" } }, "text/html": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } } } } } } }, "/content/{id}/publish": { "post": { "operationId": "publishContent", "summary": "Publish content to CMS", "description": "Publish content to a connected CMS platform (Frase CMS, WordPress, Webflow, or Sanity). The content must exist and the CMS must be connected to the specified site.", "tags": [ "Content" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Content ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "destination", "site_id" ], "properties": { "destination": { "type": "string", "enum": [ "frase_cms", "wordpress", "webflow", "sanity" ], "description": "Target CMS platform" }, "site_id": { "type": "string", "format": "uuid", "description": "Site ID with the CMS connection" }, "status": { "type": "string", "enum": [ "publish", "draft" ], "default": "draft", "description": "Publish status (default: draft for safety)" }, "scheduled_at": { "type": "string", "format": "date-time", "description": "ISO 8601 datetime for scheduled publishing" } } } } } }, "responses": { "200": { "description": "Content published successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "success": { "type": "boolean" }, "destination": { "type": "string" }, "url": { "type": "string", "nullable": true, "description": "Published URL" }, "external_id": { "type": "string", "nullable": true, "description": "External CMS item ID" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/content/{id}/regenerate": { "post": { "operationId": "regenerateContent", "summary": "Regenerate or improve content", "description": "Regenerate content from its brief (full regeneration) or improve it with specific instructions. When instructions are provided, the content is rewritten using AI with those instructions. Without instructions, the content is fully regenerated from its brief. Both operations run asynchronously.", "tags": [ "Content" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Content ID" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "instructions": { "type": "string", "maxLength": 2000, "description": "Improvement instructions for AI rewriting. If omitted, content is fully regenerated from its brief." }, "brief_id": { "type": "string", "format": "uuid", "description": "Brief ID to regenerate from. Uses the content's linked brief if not specified." } } } } } }, "responses": { "202": { "description": "Regeneration started", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "generating", "improving" ] }, "brief_id": { "type": "string", "format": "uuid" }, "status_url": { "type": "string", "description": "URL to check generation status" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/content/{id}/rescore": { "post": { "operationId": "rescoreContent", "summary": "Recalculate content scores", "description": "Recalculate SEO, GEO, and EEAT scores for a content item. This is a lightweight, synchronous operation (~50ms) that uses zero external API calls. Scores are persisted to the database. Available on all plans.", "tags": [ "Content" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Content ID" } ], "responses": { "200": { "description": "Scores recalculated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "scores": { "type": "object", "properties": { "seo_score": { "type": "integer", "minimum": 0, "maximum": 100 }, "seo_breakdown": { "type": "object" }, "geo_score": { "type": "integer", "minimum": 0, "maximum": 100 }, "geo_breakdown": { "type": "object" }, "eeat_score": { "type": "integer", "minimum": 0, "maximum": 100 }, "eeat_breakdown": { "type": "object" } } }, "rescored_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "Content has no body to score", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "retry_after": { "type": "integer", "description": "Seconds until rate limit resets" } } } } } } } } }, "/sites/{siteId}/cms-connections": { "get": { "operationId": "listCmsConnections", "summary": "List CMS connections", "description": "List the connection status of all supported CMS platforms (Frase CMS, WordPress, Webflow, Sanity) for a given site.", "tags": [ "Sites" ], "parameters": [ { "name": "siteId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Site ID" } ], "responses": { "200": { "description": "CMS connection statuses", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "connections": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "frase_cms", "wordpress", "webflow", "sanity" ] }, "connected": { "type": "boolean" } } } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/briefs": { "get": { "operationId": "listBriefs", "summary": "List briefs", "description": "Retrieve all content briefs.", "tags": [ "Briefs" ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 20 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "draft", "pending", "research", "ready", "generating", "completed" ] } }, { "name": "site_id", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Filter briefs by site ID" } ], "responses": { "200": { "description": "List of briefs", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "topic": { "type": "string" }, "target_keywords": { "type": "array", "items": { "type": "string" } }, "content_type": { "type": "string" }, "status": { "type": "string" }, "search_intent": { "type": "string", "nullable": true }, "target_word_count": { "type": "integer", "nullable": true }, "site_id": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } } } }, "request_id": { "type": "string" }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } } } }, "post": { "operationId": "createBrief", "summary": "Create brief", "description": "Create a content brief from a completed research session. The brief is generated from the full research context (keywords, SERP headings, content gaps, evidence, AI visibility, search intent) using the same pipeline as the Frase app. The brief is created immediately with `status: \"pending\"` and populated asynchronously. Poll `status_url` to check when the outline is ready.", "tags": [ "Briefs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "research_session_id" ], "properties": { "research_session_id": { "type": "string", "format": "uuid", "description": "ID of a completed research session (from POST /research). The brief topic, keywords, and outline are generated from the research data." }, "content_type": { "type": "string", "enum": [ "blog", "guide", "landing", "product", "comparison" ], "default": "blog", "description": "Content type for the brief" }, "target_word_count": { "type": "integer", "minimum": 500, "maximum": 10000, "default": 2000, "description": "Target word count for the article" } } } } } }, "responses": { "201": { "description": "Brief created. When `research_session_id` is provided, the brief is created with `status: \"pending\"` and will be populated asynchronously with the research-backed content plan. Poll `status_url` to check progress.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "topic": { "type": "string" }, "target_keywords": { "type": "array", "items": { "type": "string" } }, "content_type": { "type": "string" }, "status": { "type": "string", "description": "Brief status. 'pending' when created from research (outline generating). 'draft' for standard briefs without auto-outline. 'ready' when outline is complete." }, "created_at": { "type": "string", "format": "date-time" }, "brief_url": { "type": "string", "description": "URL to view the brief in the Frase app" }, "status_url": { "type": "string", "nullable": true, "description": "URL to poll for outline generation status" }, "research_session_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Research session ID (present when brief was created from research)" } } }, "request_id": { "type": "string" } } } } } }, "409": { "description": "Brief generation already in progress for this research session" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/briefs/{id}": { "get": { "operationId": "getBrief", "summary": "Get brief", "description": "Retrieve a specific brief by ID. The outline field contains sections in snake_case format.", "tags": [ "Briefs" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Brief details including outline sections", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "topic": { "type": "string" }, "target_keywords": { "type": "array", "items": { "type": "string" } }, "content_type": { "type": "string" }, "status": { "type": "string" }, "search_intent": { "type": "string", "nullable": true }, "target_word_count": { "type": "integer", "nullable": true }, "outline": { "type": "array", "items": { "$ref": "#/components/schemas/ContentOutlineSection" } }, "competitor_urls": { "type": "array", "items": { "type": "string" } }, "notes": { "type": "string", "nullable": true }, "questions_to_answer": { "type": "array", "items": { "type": "string" } }, "unique_angle": { "type": "string", "nullable": true }, "target_language": { "type": "string", "nullable": true }, "target_country": { "type": "string", "nullable": true }, "authority_source": { "type": "string", "nullable": true }, "blog_format": { "type": "string", "nullable": true }, "guide_format": { "type": "string", "nullable": true }, "is_imported": { "type": "boolean" }, "imported_content_url": { "type": "string", "nullable": true }, "progress_details": { "type": "object", "nullable": true }, "linked_content": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "title": { "type": "string" } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } } }, "request_id": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "description": "Internal server error" } } }, "put": { "operationId": "updateBrief", "summary": "Update brief", "description": "Update brief metadata and/or set a custom outline. To set a custom outline, include the `outline` array. To update only metadata (topic, keywords, etc.), omit `outline`. Cannot update outline while brief generation is in progress (status='pending', 'generating', or 'research').", "tags": [ "Briefs" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "topic": { "type": "string", "maxLength": 500 }, "target_keywords": { "type": "array", "items": { "type": "string" } }, "content_type": { "type": "string", "enum": [ "blog", "guide", "landing", "product", "comparison", "listicle" ] }, "search_intent": { "type": "string", "description": "Search intent classification", "enum": [ "informational", "navigational", "transactional", "commercial" ] }, "target_word_count": { "type": "integer", "minimum": 0 }, "outline": { "type": "array", "description": "Custom content outline sections. When provided, replaces the entire outline. Each section defines a heading for content generation.", "minItems": 1, "maxItems": 50, "items": { "$ref": "#/components/schemas/ContentOutlineSection" } }, "variation_overrides": { "type": "object", "description": "Override content variation parameters (tone, voice, angle).", "properties": { "tone": { "type": "string", "description": "Writing tone (e.g. 'professional', 'conversational')" }, "voice_persona": { "type": "string", "description": "Voice persona for content generation" }, "angle": { "type": "string", "description": "Content angle or perspective" } } }, "audience_context": { "type": "object", "description": "Target audience context for content generation.", "properties": { "role": { "type": "string" }, "expertise": { "type": "string", "enum": [ "beginner", "intermediate", "expert" ] }, "pain_point": { "type": "string" }, "funnel_stage": { "type": "string", "enum": [ "awareness", "consideration", "decision" ] } } }, "topic_guardrails": { "type": "object", "description": "Topic guardrails for content generation.", "required": [ "required", "excluded" ], "properties": { "required": { "type": "array", "items": { "type": "string" }, "description": "Topics that must be covered" }, "excluded": { "type": "array", "items": { "type": "string" }, "description": "Topics to avoid" } } } } } } } }, "responses": { "200": { "description": "Brief updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "topic": { "type": "string" }, "target_keywords": { "type": "array", "items": { "type": "string" } }, "content_type": { "type": "string" }, "status": { "type": "string" }, "outline_section_count": { "type": "integer", "description": "Returned when outline is updated" }, "updated_at": { "type": "string", "format": "date-time" } } }, "request_id": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "description": "Internal server error" } } } }, "/briefs/{id}/status": { "get": { "operationId": "getBriefStatus", "summary": "Get brief generation status", "description": "Check the status of brief research and generation.", "tags": [ "Briefs" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Brief status", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "topic": { "type": "string" }, "status": { "type": "string" }, "is_processing": { "type": "boolean" }, "is_complete": { "type": "boolean" }, "is_failed": { "type": "boolean" }, "progress": { "type": "object", "properties": { "current_step": { "type": "string" }, "completed_steps": { "type": "integer" }, "total_steps": { "type": "integer" }, "percent_complete": { "type": "integer" } } }, "error": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } } }, "request_id": { "type": "string" } } } } } } } } }, "/briefs/{id}/export": { "get": { "operationId": "exportBrief", "summary": "Export brief", "description": "Export brief in JSON or Markdown format.", "tags": [ "Briefs" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "markdown" ], "default": "json" } } ], "responses": { "200": { "description": "Exported brief", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "topic": { "type": "string" }, "target_keywords": { "type": "array", "items": { "type": "string" } }, "content_type": { "type": "string" }, "target_word_count": { "type": "integer" }, "outline": { "type": "array", "items": { "$ref": "#/components/schemas/ContentOutlineSection" } }, "competitor_urls": { "type": "array", "items": { "type": "string" } }, "notes": { "type": "string", "nullable": true }, "questions_to_answer": { "type": "array", "items": { "type": "string" } }, "unique_angle": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "export_format": { "type": "string" }, "exported_at": { "type": "string", "format": "date-time" } } }, "request_id": { "type": "string" } } } }, "text/markdown": { "schema": { "type": "string" } } } } } } }, "/research": { "get": { "operationId": "listResearch", "summary": "List research", "description": "Retrieve all research sessions in your organization.", "tags": [ "Research" ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } }, { "name": "site_id", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Filter research sessions by site ID" } ], "responses": { "200": { "description": "List of research sessions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResearch" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "operationId": "startResearch", "summary": "Start research", "description": "Start AI-powered research on a topic. Research runs asynchronously \u2014 use the returned session ID with GET /research/{id} to check progress. The research_url field provides a direct link to view the research in the Frase app.", "tags": [ "Research" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query", "site_id" ], "properties": { "query": { "type": "string", "minLength": 2, "maxLength": 500, "description": "The topic or search query to research" }, "site_id": { "type": "string", "format": "uuid", "description": "The site to associate the research with (required). Provides brand context, language, and country defaults." }, "type": { "type": "string", "enum": [ "general", "topic", "competitor", "gap" ], "default": "general", "description": "Research type. 'general' runs keywords + SERP + gaps + evidence + AI visibility. 'topic' maps subtopic directions. 'competitor' and 'gap' run the general pipeline with type-specific strategy context." }, "language": { "type": "string", "description": "Language code (e.g., 'en'). Falls back to site language if omitted." }, "country": { "type": "string", "description": "Country code (e.g., 'US'). Falls back to site country if omitted." }, "competitor_domains": { "type": "array", "items": { "type": "string" }, "description": "Competitor domains to analyze (used with type=competitor or type=gap)" }, "audience": { "type": "string", "description": "Target audience context for research" }, "objective": { "type": "string", "description": "Content objective \u2014 what the research should accomplish" }, "focus": { "type": "string", "description": "Focus area or differentiation lens" } } } } } }, "responses": { "201": { "description": "Research started", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "query": { "type": "string" }, "status": { "type": "string" }, "type": { "type": "string", "nullable": true }, "language": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "research_url": { "type": "string", "description": "URL to view the research session in the Frase app" } } }, "request_id": { "type": "string" } } } } } }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/research/{id}": { "get": { "operationId": "getResearch", "summary": "Get research", "description": "Retrieve a specific research session by ID.", "tags": [ "Research" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Research details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Research" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "operationId": "deleteResearch", "summary": "Delete research", "description": "Soft delete a research session (moves to trash).", "tags": [ "Research" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Research deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/research/{id}/export": { "get": { "operationId": "exportResearch", "summary": "Export research", "description": "Export research findings in JSON or Markdown format.", "tags": [ "Research" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "markdown" ], "default": "json" } } ], "responses": { "200": { "description": "Exported research", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResearchExport" } }, "text/markdown": { "schema": { "type": "string" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/audits": { "get": { "operationId": "listAudits", "summary": "List audits", "description": "Retrieve all site audits.", "tags": [ "Audits" ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 20 } }, { "name": "site_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "crawling", "analyzing", "completed", "failed" ] } } ], "responses": { "200": { "description": "List of audits", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "nullable": true }, "type": { "type": "string" }, "status": { "type": "string" }, "progress": { "type": "integer", "nullable": true }, "pages_audited": { "type": "integer" }, "total_issues": { "type": "integer" }, "critical_issues": { "type": "integer" }, "overall_score": { "type": "integer", "nullable": true }, "site": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "domain": { "type": "string" } } }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true } } } }, "request_id": { "type": "string" }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } } } }, "post": { "operationId": "startAudit", "summary": "Start audit", "description": "Start a new site audit.", "tags": [ "Audits" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "site_id" ], "properties": { "site_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "description": "Custom audit name" }, "type": { "type": "string", "enum": [ "full", "quick", "technical" ] }, "max_pages": { "type": "integer", "description": "Maximum pages to crawl" }, "selected_page_urls": { "type": "array", "items": { "type": "string" }, "description": "Specific URLs to audit" }, "settings": { "type": "object", "description": "Advanced audit settings" } } } } } }, "responses": { "201": { "description": "Audit started", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "nullable": true }, "type": { "type": "string" }, "status": { "type": "string" }, "site": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "domain": { "type": "string" } } }, "created_at": { "type": "string", "format": "date-time" } } }, "request_id": { "type": "string" } } } } } } } } }, "/audits/{id}": { "get": { "operationId": "getAudit", "summary": "Get audit", "description": "Retrieve audit details and summary.", "tags": [ "Audits" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "include_pages", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Include audited pages in response" }, { "name": "page_limit", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Max pages to include (when include_pages=true)" } ], "responses": { "200": { "description": "Audit details", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "nullable": true }, "type": { "type": "string" }, "status": { "type": "string" }, "progress": { "type": "integer", "nullable": true }, "pages_audited": { "type": "integer" }, "total_issues": { "type": "integer" }, "critical_issues": { "type": "integer" }, "overall_score": { "type": "integer", "nullable": true }, "summary": { "type": "object", "nullable": true }, "site": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "domain": { "type": "string" } } }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "pages": { "type": "array", "nullable": true, "description": "Included when include_pages=true", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "title": { "type": "string", "nullable": true }, "status_code": { "type": "integer", "nullable": true }, "score": { "type": "integer", "nullable": true }, "issues": { "type": "array", "items": { "type": "object" } } } } } } }, "request_id": { "type": "string" } } } } } } } } }, "/audits/{id}/export": { "get": { "operationId": "exportAudit", "summary": "Export audit", "description": "Export audit report in JSON or CSV format.", "tags": [ "Audits" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "csv" ], "default": "json" } } ], "responses": { "200": { "description": "Exported audit", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "site_id": { "type": "string", "nullable": true }, "site_domain": { "type": "string", "nullable": true }, "type": { "type": "string" }, "status": { "type": "string" }, "summary": { "type": "object", "properties": { "total_pages": { "type": "integer" }, "crawled_pages": { "type": "integer" }, "avg_word_count": { "type": "number" }, "total_issues": { "type": "integer" }, "critical_issues": { "type": "integer" }, "warning_issues": { "type": "integer" } } }, "pages": { "type": "array", "items": { "type": "object" } }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "export_format": { "type": "string" }, "exported_at": { "type": "string", "format": "date-time" } } }, "request_id": { "type": "string" } } } }, "text/csv": { "schema": { "type": "string" } } } } } } }, "/audits/page": { "post": { "operationId": "auditPage", "summary": "Audit a single page", "description": "Scrape and audit a single URL, returning E-E-A-T, GEO, and SEO scores along with detected issues. The endpoint auto-routes based on site context: if the URL belongs to a site with no existing audit, a scoped site audit is started asynchronously (202); otherwise, the audit runs synchronously (201).", "tags": [ "Audits" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "The URL to audit. Must be http or https." }, "keyword": { "type": "string", "description": "Optional target keyword for SEO scoring context." }, "audit_page_id": { "type": "string", "format": "uuid", "description": "Optional audit page ID. When provided, re-audits the page within its site audit context, updating the auditPages row and recalculating the parent audit score." }, "site_audit_id": { "type": "string", "format": "uuid", "description": "Optional site audit ID. Used together with audit_page_id to specify which site audit the page belongs to." }, "site_id": { "type": "string", "format": "uuid", "description": "Optional site ID. When provided, the endpoint uses this site for routing instead of auto-detecting by domain." } } } } } }, "responses": { "201": { "description": "Audit completed successfully (synchronous). Returned for routes: standalone, reaudit_in_site_audit, add_to_site_audit.", "content": { "application/json": { "schema": { "type": "object", "properties": { "route": { "type": "string", "enum": [ "standalone", "reaudit_in_site_audit", "add_to_site_audit" ], "description": "The routing path taken by the endpoint." }, "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "status": { "type": "string", "enum": [ "completed", "failed" ] }, "keyword": { "type": "string", "nullable": true }, "content_type": { "type": "string", "enum": [ "article", "marketing", "documentation", "ecommerce", "unknown" ] }, "content_type_confidence": { "type": "number" }, "title": { "type": "string", "nullable": true }, "meta_description": { "type": "string", "nullable": true }, "word_count": { "type": "integer" }, "overall_score": { "type": "integer", "minimum": 0, "maximum": 100 }, "eeat_score": { "type": "integer", "minimum": 0, "maximum": 100 }, "eeat_breakdown": { "type": "object" }, "geo_score": { "type": "integer", "minimum": 0, "maximum": 100 }, "geo_breakdown": { "type": "object" }, "seo_score": { "type": "integer", "minimum": 0, "maximum": 100 }, "seo_breakdown": { "type": "object" }, "issues": { "type": "array", "items": { "type": "object" } }, "headings": { "type": "array", "items": { "type": "object", "properties": { "level": { "type": "integer" }, "text": { "type": "string" } } } }, "outbound_links": { "type": "array", "items": { "type": "string" } }, "author_name": { "type": "string", "nullable": true }, "analyzed_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } } } } }, "202": { "description": "Scoped site audit started asynchronously. Returned when the URL belongs to a site with no completed audit. Poll the audit status endpoint for progress.", "content": { "application/json": { "schema": { "type": "object", "properties": { "route": { "type": "string", "enum": [ "scoped_site_audit" ] }, "audit_id": { "type": "string", "format": "uuid", "description": "The ID of the newly created site audit." }, "message": { "type": "string" }, "status_url": { "type": "string", "format": "uri", "description": "URL to poll for audit status." } } } } } }, "422": { "description": "Invalid URL" }, "429": { "description": "Audit page limit exceeded" } } } }, "/ai-visibility": { "get": { "operationId": "getAIVisibilityOverview", "summary": "Get AI visibility overview", "description": "Get an overview of your brand visibility across AI platforms.", "tags": [ "AI Visibility" ], "parameters": [ { "name": "days", "in": "query", "description": "Number of days to look back (1-90)", "schema": { "type": "integer", "default": 30, "minimum": 1, "maximum": 90 } } ], "responses": { "200": { "description": "AI visibility overview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIVisibilityOverview" } } } } } } }, "/ai-visibility/prompts": { "get": { "operationId": "listTrackedPrompts", "summary": "List tracked prompts", "description": "List all prompts being tracked for AI visibility.", "tags": [ "AI Visibility" ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 20 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "paused", "archived" ] } } ], "responses": { "200": { "description": "List of tracked prompts", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "prompt_text": { "type": "string" }, "status": { "type": "string" }, "frequency": { "type": "string" }, "target_brand": { "type": "string" }, "last_checked_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } } } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } } } }, "post": { "operationId": "createTrackedPrompt", "summary": "Add tracked prompt", "description": "Add a new prompt to track for AI visibility.", "tags": [ "AI Visibility" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "prompt_text", "target_brand" ], "properties": { "prompt_text": { "type": "string", "minLength": 10, "maxLength": 1000 }, "target_brand": { "type": "string", "maxLength": 255 }, "brand_variants": { "type": "array", "items": { "type": "string" } }, "frequency": { "type": "string", "enum": [ "daily", "weekly", "manual" ] }, "platforms": { "type": "array", "items": { "type": "string", "enum": [ "chatgpt", "perplexity", "claude", "gemini", "google_ai", "grok", "copilot", "deepseek" ] } } } } } } }, "responses": { "201": { "description": "Prompt created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "prompt_text": { "type": "string" }, "target_brand": { "type": "string" }, "frequency": { "type": "string" }, "platforms": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "request_id": { "type": "string" } } } } } } } } }, "/ai-visibility/prompts/{id}": { "get": { "operationId": "getTrackedPrompt", "summary": "Get tracked prompt", "description": "Get details of a tracked prompt with historical results.", "tags": [ "AI Visibility" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "include_results", "in": "query", "schema": { "type": "boolean", "default": true } }, { "name": "result_limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } } ], "responses": { "200": { "description": "Prompt details with results", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "prompt_text": { "type": "string" }, "target_brand": { "type": "string" }, "brand_variants": { "type": "array", "items": { "type": "string" } }, "frequency": { "type": "string" }, "platforms": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "latest_visibility_score": { "type": "number", "nullable": true }, "last_checked_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "nullable": true }, "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "platform": { "type": "string" }, "mention_count": { "type": "integer" }, "citation_url": { "type": "string", "nullable": true }, "response_snippet": { "type": "string", "nullable": true }, "sentiment_score": { "type": "number", "nullable": true }, "visibility_score": { "type": "number", "nullable": true }, "checked_at": { "type": "string", "format": "date-time" } } } } } }, "request_id": { "type": "string" } } } } } } } }, "patch": { "operationId": "updateTrackedPrompt", "summary": "Update tracked prompt", "description": "Update prompt status, frequency, or platforms.", "tags": [ "AI Visibility" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active", "paused", "archived" ] }, "frequency": { "type": "string", "enum": [ "daily", "weekly", "manual" ] }, "platforms": { "type": "array", "items": { "type": "string" } }, "brand_variants": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Prompt updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "frequency": { "type": "string" }, "platforms": { "type": "array", "items": { "type": "string" } }, "updated_at": { "type": "string", "format": "date-time" } } }, "request_id": { "type": "string" } } } } } } } } }, "/ai-visibility/competitors": { "get": { "operationId": "getAICompetitors", "summary": "Get competitor analysis", "description": "Get competitive share-of-voice analysis across AI platforms.", "tags": [ "AI Visibility" ], "responses": { "200": { "description": "Competitor analysis", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "domain": { "type": "string" }, "variants": { "type": "array", "items": { "type": "string" } }, "latest_visibility_score": { "type": "number", "nullable": true }, "last_tracked_at": { "type": "string", "format": "date-time", "nullable": true }, "share_of_voice": { "type": "object", "properties": { "total_mentions": { "type": "integer" }, "avg_score": { "type": "number" }, "platforms": { "type": "object" } } }, "created_at": { "type": "string", "format": "date-time" } } } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } } }, "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 20 } }, { "name": "days", "in": "query", "schema": { "type": "integer", "default": 30 }, "description": "Lookback period in days" } ] } }, "/ai-visibility/alerts": { "get": { "operationId": "getAIVisibilityAlerts", "summary": "Get visibility alerts", "description": "Get alerts for visibility changes.", "tags": [ "AI Visibility" ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 20 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "unread", "resolved", "all" ] }, "description": "Filter by alert status" }, { "name": "severity", "in": "query", "schema": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] } }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "visibility_increase", "visibility_decrease", "new_mention", "lost_mention", "competitor_overtake", "citation_gained", "citation_lost", "crawler_spike" ] } } ], "responses": { "200": { "description": "List of alerts", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "severity": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "data": { "type": "object" }, "platform": { "type": "string", "nullable": true }, "is_read": { "type": "boolean" }, "read_at": { "type": "string", "format": "date-time", "nullable": true }, "resolved_at": { "type": "string", "format": "date-time", "nullable": true }, "prompt_id": { "type": "string", "nullable": true }, "site_id": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } } } } }, "/ai-visibility/insights": { "get": { "operationId": "getAIVisibilityInsights", "summary": "Get optimization insights", "description": "Get AI-generated insights for improving visibility.", "tags": [ "AI Visibility" ], "responses": { "200": { "description": "Optimization insights", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "status": { "type": "string" }, "gap_type": { "type": "string", "nullable": true }, "diagnosis": { "type": "string", "nullable": true }, "confidence_score": { "type": "number", "nullable": true }, "target_url": { "type": "string", "nullable": true }, "winning_competitor_url": { "type": "string", "nullable": true }, "prompt_id": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } } } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } } }, "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 20 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "idle", "scraping", "analyzing", "ready", "applied", "failed" ] } } ] } }, "/ai-visibility/crawler-logs": { "get": { "operationId": "getAICrawlerLogs", "summary": "Get AI crawler logs", "description": "View AI bot activity on your sites.", "tags": [ "AI Visibility" ], "parameters": [ { "name": "site_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "platform", "in": "query", "schema": { "type": "string" } }, { "name": "days", "in": "query", "schema": { "type": "integer", "default": 30, "maximum": 90 } }, { "name": "group_by", "in": "query", "schema": { "type": "string", "enum": [ "none", "day", "platform", "path" ], "default": "none" }, "description": "Group results by dimension" } ], "responses": { "200": { "description": "Crawler logs", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "site_id": { "type": "string" }, "site_domain": { "type": "string" }, "platform": { "type": "string" }, "bot_name": { "type": "string" }, "user_agent": { "type": "string" }, "url": { "type": "string" }, "path": { "type": "string" }, "status_code": { "type": "integer" }, "was_blocked": { "type": "boolean" }, "crawled_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } } } } }, "/analytics/gsc/overview": { "get": { "operationId": "getGSCOverview", "summary": "Get GSC overview", "description": "Get Google Search Console overview with 28-day comparison.", "tags": [ "Analytics" ], "parameters": [ { "name": "site_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "GSC overview data", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "site_id": { "type": "string" }, "site_domain": { "type": "string" }, "period": { "type": "object", "properties": { "current": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" } } }, "previous": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" } } } } }, "metrics": { "type": "object", "properties": { "clicks": { "type": "object", "properties": { "current": { "type": "integer" }, "previous": { "type": "integer" }, "change_percent": { "type": "number" } } }, "impressions": { "type": "object", "properties": { "current": { "type": "integer" }, "previous": { "type": "integer" }, "change_percent": { "type": "number" } } }, "ctr": { "type": "object", "properties": { "current": { "type": "number" }, "previous": { "type": "number" }, "change_percent": { "type": "number" } } }, "position": { "type": "object", "properties": { "current": { "type": "number" }, "previous": { "type": "number" }, "change_percent": { "type": "number" } } } } }, "summary": { "type": "object", "properties": { "unique_queries": { "type": "integer" }, "unique_pages": { "type": "integer" } } } } }, "request_id": { "type": "string" } } } } } } } } }, "/analytics/gsc/queries": { "get": { "operationId": "getGSCQueries", "summary": "Get top queries", "description": "Get top search queries from GSC.", "tags": [ "Analytics" ], "parameters": [ { "name": "site_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 500 } }, { "name": "days", "in": "query", "schema": { "type": "integer", "default": 28 } }, { "name": "sort_by", "in": "query", "schema": { "type": "string", "enum": [ "clicks", "impressions", "ctr", "position" ], "default": "clicks" } } ], "responses": { "200": { "description": "Top queries", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "query": { "type": "string" }, "clicks": { "type": "integer" }, "impressions": { "type": "integer" }, "ctr": { "type": "number" }, "position": { "type": "number" }, "pages_count": { "type": "integer" } } } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } } } } }, "/analytics/gsc/pages": { "get": { "operationId": "getGSCPages", "summary": "Get top pages", "description": "Get top pages by performance from GSC.", "tags": [ "Analytics" ], "parameters": [ { "name": "site_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 50 } }, { "name": "days", "in": "query", "schema": { "type": "integer", "default": 28 } }, { "name": "sort_by", "in": "query", "schema": { "type": "string", "enum": [ "clicks", "impressions", "ctr", "position" ], "default": "clicks" } } ], "responses": { "200": { "description": "Top pages", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "page_url": { "type": "string" }, "content_id": { "type": "string", "nullable": true }, "content_title": { "type": "string", "nullable": true }, "clicks": { "type": "integer" }, "impressions": { "type": "integer" }, "ctr": { "type": "number" }, "position": { "type": "number" }, "queries_count": { "type": "integer" } } } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } } } } }, "/analytics/gaps": { "get": { "operationId": "getContentGaps", "summary": "Get content gaps", "description": "Get content gap opportunities.", "tags": [ "Analytics" ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 20 } }, { "name": "site_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "new", "reviewed", "in_progress", "dismissed", "completed" ] } }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "missing_content", "thin_content", "outdated_content", "competitor_gap" ] } } ], "responses": { "200": { "description": "Content gaps", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "site_id": { "type": "string", "nullable": true }, "site_domain": { "type": "string", "nullable": true }, "keyword": { "type": "string" }, "search_volume": { "type": "integer", "nullable": true }, "difficulty": { "type": "number", "nullable": true }, "opportunity_type": { "type": "string" }, "impressions": { "type": "integer", "nullable": true }, "clicks": { "type": "integer", "nullable": true }, "avg_position": { "type": "number", "nullable": true }, "page_url": { "type": "string", "nullable": true }, "existing_content_id": { "type": "string", "nullable": true }, "suggested_brief_id": { "type": "string", "nullable": true }, "competitor_urls": { "type": "array", "items": { "type": "string" }, "nullable": true }, "competitor_analysis": { "type": "object", "nullable": true }, "status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } } } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } } } } }, "/analytics/alerts": { "get": { "operationId": "getPerformanceAlerts", "summary": "Get performance alerts", "description": "Get performance alerts (traffic drops, etc.).", "tags": [ "Analytics" ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 20 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "unresolved", "resolved", "all" ] }, "description": "Filter by resolution status" }, { "name": "severity", "in": "query", "schema": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] } }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "ranking_drop", "traffic_drop", "decay_detected" ] } } ], "responses": { "200": { "description": "Performance alerts", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "content_id": { "type": "string", "nullable": true }, "content_title": { "type": "string", "nullable": true }, "content_status": { "type": "string", "nullable": true }, "type": { "type": "string" }, "severity": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "data": { "type": "object" }, "has_optimization": { "type": "boolean" }, "resolved_at": { "type": "string", "format": "date-time", "nullable": true }, "resolution": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } } } } }, "/analytics/alerts/{id}/resolve": { "post": { "operationId": "resolveAlert", "summary": "Resolve alert", "description": "Mark an alert as resolved.", "tags": [ "Analytics" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "resolution": { "type": "string", "maxLength": 1000 } } } } } }, "responses": { "200": { "description": "Alert resolved", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "resolved_at": { "type": "string", "format": "date-time" }, "resolution": { "type": "string", "nullable": true }, "message": { "type": "string" } } }, "request_id": { "type": "string" } } } } } } } } }, "/serp/analyze": { "post": { "operationId": "analyzeSERP", "summary": "Analyze SERP", "description": "Analyze search results for a keyword, including AI Overview and PAA.", "tags": [ "SERP" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "keyword" ], "properties": { "keyword": { "type": "string", "minLength": 2, "maxLength": 200 }, "location": { "type": "string", "default": "United States" }, "country_code": { "type": "string", "default": "us" }, "language_code": { "type": "string", "default": "en" }, "num": { "type": "integer", "default": 10, "maximum": 20, "minimum": 5, "description": "Number of SERP results to fetch" } } } } } }, "responses": { "200": { "description": "SERP analysis", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SERPAnalysis" } } } } } } }, "/serp/competitors": { "post": { "operationId": "analyzeCompetitors", "summary": "Analyze competitors", "description": "Compare a URL against SERP competitors for a keyword.", "tags": [ "SERP" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "keyword", "url" ], "properties": { "keyword": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "location": { "type": "string" }, "country_code": { "type": "string" }, "language_code": { "type": "string" } } } } } }, "responses": { "200": { "description": "Competitor analysis", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "keyword": { "type": "string" }, "target_url": { "type": "string" }, "target_domain": { "type": "string" }, "search_parameters": { "type": "object" }, "target_visibility": { "type": "object", "properties": { "is_ranking": { "type": "boolean" }, "position": { "type": "integer", "nullable": true }, "title": { "type": "string", "nullable": true }, "snippet": { "type": "string", "nullable": true } } }, "competitive_analysis": { "type": "object", "properties": { "total_competitors": { "type": "integer" }, "competitors": { "type": "array", "items": { "type": "object" } } } }, "opportunities": { "type": "object" } } }, "request_id": { "type": "string" } } } } } } } } }, "/serp/intent": { "post": { "operationId": "classifyIntent", "summary": "Classify search intent", "description": "Classify the search intent for a keyword.", "tags": [ "SERP" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "keyword" ], "properties": { "keyword": { "type": "string" } } } } } }, "responses": { "200": { "description": "Intent classification", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "keyword": { "type": "string" }, "search_parameters": { "type": "object" }, "intent_classification": { "type": "object", "properties": { "primary_intent": { "type": "string" }, "confidence": { "type": "number" }, "scores": { "type": "object", "properties": { "informational": { "type": "number" }, "navigational": { "type": "number" }, "transactional": { "type": "number" }, "commercial": { "type": "number" } } } } }, "serp_signals": { "type": "object" }, "recommendations": { "type": "array", "items": { "type": "string" } }, "content_type_suggestions": { "type": "array", "items": { "type": "string" } } } }, "request_id": { "type": "string" } } } } } } } } }, "/optimizations": { "get": { "operationId": "listOptimizations", "summary": "List optimizations", "description": "List content optimization analyses.", "tags": [ "Optimizations" ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 20 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "analyzing", "ready", "auto_applying", "applied", "dismissed", "failed" ] } }, { "name": "content_id", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Filter by content ID" } ], "responses": { "200": { "description": "List of optimizations", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "content_id": { "type": "string" }, "alert_id": { "type": "string", "nullable": true }, "status": { "type": "string" }, "suggestions_count": { "type": "integer" }, "applied_count": { "type": "integer" }, "error": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "nullable": true }, "analyzed_at": { "type": "string", "format": "date-time", "nullable": true } } } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } } } }, "post": { "operationId": "startOptimization", "summary": "Start optimization", "description": "Start optimization analysis for content.", "tags": [ "Optimizations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "content_id" ], "properties": { "content_id": { "type": "string", "format": "uuid" }, "alert_id": { "type": "string", "format": "uuid", "description": "Optional performance alert that triggered this optimization" } } } } } }, "responses": { "201": { "description": "Optimization started", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "content_id": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "request_id": { "type": "string" } } } } } } } } }, "/optimizations/{id}": { "get": { "operationId": "getOptimization", "summary": "Get optimization", "description": "Get optimization details and suggestions.", "tags": [ "Optimizations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Optimization details", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "content_id": { "type": "string" }, "content_title": { "type": "string", "nullable": true }, "content_status": { "type": "string", "nullable": true }, "alert_id": { "type": "string", "nullable": true }, "status": { "type": "string" }, "competitor_analysis": { "type": "object", "nullable": true }, "suggestions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "priority": { "type": "string" }, "content": { "type": "string", "nullable": true }, "auto_applyable": { "type": "boolean" }, "is_applied": { "type": "boolean" } } } }, "applied_suggestion_ids": { "type": "array", "items": { "type": "string" } }, "error": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "nullable": true }, "analyzed_at": { "type": "string", "format": "date-time", "nullable": true } } }, "request_id": { "type": "string" } } } } } } } } }, "/optimizations/{id}/apply": { "post": { "operationId": "applyOptimization", "summary": "Apply suggestion", "description": "Apply an optimization suggestion.", "tags": [ "Optimizations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "suggestion_id": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Suggestion applied", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "suggestion_id": { "type": "string" }, "suggestion_type": { "type": "string" }, "suggestion_title": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } } }, "request_id": { "type": "string" } } } } } } } } }, "/optimizations/{id}/dismiss": { "post": { "operationId": "dismissOptimization", "summary": "Dismiss optimization", "description": "Dismiss an optimization.", "tags": [ "Optimizations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Optimization dismissed", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "reason": { "type": "string", "nullable": true }, "message": { "type": "string" } } }, "request_id": { "type": "string" } } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Optional reason for dismissing", "maxLength": 1000 } } } } } } } }, "/optimizations/insights": { "get": { "operationId": "getOptimizationInsights", "summary": "Get learning insights", "description": "Get insights about what's working based on optimization outcomes.", "tags": [ "Optimizations" ], "responses": { "200": { "description": "Learning insights", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "period": { "type": "object", "properties": { "days": { "type": "integer" }, "since": { "type": "string", "format": "date-time" } } }, "summary": { "type": "object", "properties": { "total_optimizations_measured": { "type": "integer" }, "total_improved": { "type": "integer" }, "overall_success_rate": { "type": "number" } } }, "insights_by_type": { "type": "array", "items": { "type": "object", "properties": { "suggestion_type": { "type": "string" }, "total_applied": { "type": "integer" }, "successful_count": { "type": "integer" }, "success_rate": { "type": "number" }, "avg_position_improvement": { "type": "number" }, "avg_clicks_change": { "type": "number" } } } }, "top_performers": { "type": "array", "items": { "type": "object" } }, "recommendations": { "type": "array", "items": { "type": "string" } } } }, "request_id": { "type": "string" } } } } } } }, "parameters": [ { "name": "days", "in": "query", "schema": { "type": "integer", "default": 30, "minimum": 7, "maximum": 90 }, "description": "Lookback period in days" } ] } }, "/webhooks": { "get": { "operationId": "listWebhooks", "summary": "List webhooks", "description": "List all webhook subscriptions.", "tags": [ "Webhooks" ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "List of webhooks", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "is_active": { "type": "boolean" }, "stats": { "type": "object", "properties": { "success_count": { "type": "integer" }, "failure_count": { "type": "integer" }, "last_delivery_at": { "type": "string", "format": "date-time", "nullable": true }, "last_success_at": { "type": "string", "format": "date-time", "nullable": true }, "last_failure_at": { "type": "string", "format": "date-time", "nullable": true }, "last_failure_reason": { "type": "string", "nullable": true } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } } } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } } } }, "post": { "operationId": "createWebhook", "summary": "Create webhook", "description": "Create a new webhook subscription. The secret is only returned once.", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "url", "events" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "url": { "type": "string", "format": "uri", "description": "Must be HTTPS" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "content.ready", "content.published", "brief.ready", "research.completed", "audit.completed", "optimization.ready", "ai_visibility.alert", "performance.alert", "atomization.ready" ] } }, "is_active": { "type": "boolean", "default": true } } } } } }, "responses": { "201": { "description": "Webhook created with secret", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookWithSecret" } } } } } } }, "/webhooks/{id}": { "get": { "operationId": "getWebhook", "summary": "Get webhook", "description": "Get webhook details (secret is not included).", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Webhook details", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "is_active": { "type": "boolean" }, "config": { "type": "object", "properties": { "max_retries": { "type": "integer" }, "retry_delay_seconds": { "type": "integer" } } }, "stats": { "type": "object", "properties": { "success_count": { "type": "integer" }, "failure_count": { "type": "integer" }, "last_delivery_at": { "type": "string", "format": "date-time", "nullable": true }, "last_success_at": { "type": "string", "format": "date-time", "nullable": true }, "last_failure_at": { "type": "string", "format": "date-time", "nullable": true }, "last_failure_reason": { "type": "string", "nullable": true } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } } }, "request_id": { "type": "string" } } } } } } } }, "patch": { "operationId": "updateWebhook", "summary": "Update webhook", "description": "Update webhook settings.", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "is_active": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Webhook updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "is_active": { "type": "boolean" }, "updated_at": { "type": "string", "format": "date-time" }, "message": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "request_id": { "type": "string" } } } } } } } }, "delete": { "operationId": "deleteWebhook", "summary": "Delete webhook", "description": "Delete a webhook subscription.", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Webhook deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "deleted": { "type": "boolean" }, "message": { "type": "string" } } }, "request_id": { "type": "string" } } } } } } } } }, "/jobs/{id}/status": { "get": { "operationId": "getJobStatus", "summary": "Get job status", "description": "Check the status of an async job (audit, research, content, brief, optimization, atomization).", "tags": [ "Jobs" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "audit", "research", "content", "brief", "optimization", "atomization" ] } } ], "responses": { "200": { "description": "Job status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobStatus" } } } } } } }, "/competitive-analysis": { "get": { "operationId": "listCompetitiveAnalyses", "summary": "List competitive analyses", "description": "List all competitive page analyses for your organization.", "tags": [ "Competitive Analysis" ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "crawling_page", "fetching_rankings", "analyzing_competitors", "generating_report", "ready", "failed" ] } }, { "name": "site_id", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Filter by site ID" } ], "responses": { "200": { "description": "List of competitive analyses", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string" }, "status": { "type": "string" }, "opportunity_score": { "type": "integer", "nullable": true }, "error": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true } } } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "operationId": "startCompetitiveAnalysis", "summary": "Start competitive analysis", "description": "Start a new competitive page analysis. Crawls the target page, fetches ranking queries, discovers competitors, and generates a gap analysis.", "tags": [ "Competitive Analysis" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Target page URL to analyze" }, "competitor_urls": { "type": "array", "items": { "type": "string", "format": "uri" }, "description": "Optional manual competitor URLs. If omitted, competitors are discovered via SERP analysis." }, "site_id": { "type": "string", "format": "uuid", "description": "Optional site ID to associate the analysis with" }, "location_name": { "type": "string", "description": "Location for SERP queries (e.g., 'United States')" }, "industry": { "type": "string", "description": "Industry context for the analysis" } } } } } }, "responses": { "201": { "description": "Competitive analysis started", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string" }, "status": { "type": "string", "enum": [ "pending" ] }, "message": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "request_id": { "type": "string" } } } } } }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "description": "Audit page limit exceeded" } } } }, "/competitive-analysis/{id}": { "get": { "operationId": "getCompetitiveAnalysis", "summary": "Get competitive analysis", "description": "Get detailed results of a competitive analysis including page crawl data, ranking queries, competitor analysis, and gap analysis.", "tags": [ "Competitive Analysis" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Competitive analysis details", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "crawling_page", "fetching_rankings", "analyzing_competitors", "generating_report", "ready", "failed" ] }, "manual_competitor_urls": { "type": "array", "items": { "type": "string" }, "nullable": true }, "page_crawl": { "type": "object", "nullable": true }, "ranking_queries": { "type": "object", "nullable": true }, "serp_competitors": { "type": "object", "nullable": true }, "competitor_analysis": { "type": "object", "nullable": true }, "gap_analysis": { "type": "object", "nullable": true }, "opportunity_score": { "type": "integer", "minimum": 0, "maximum": 100, "nullable": true }, "generated_brief_id": { "type": "string", "format": "uuid", "nullable": true }, "error": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true } } }, "request_id": { "type": "string" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "operationId": "deleteCompetitiveAnalysis", "summary": "Delete competitive analysis", "description": "Permanently delete a competitive analysis and its results.", "tags": [ "Competitive Analysis" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Analysis deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "deleted": { "type": "boolean" } } }, "request_id": { "type": "string" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/competitive-analysis/{id}/generate-brief": { "post": { "operationId": "generateBriefFromCompetitiveAnalysis", "summary": "Generate brief from analysis", "description": "Generate an optimization brief from a completed competitive analysis. The analysis must have status 'ready'. This endpoint is idempotent \u2014 if a brief was already generated, it returns the existing brief ID.", "tags": [ "Competitive Analysis" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Brief already exists (idempotent)", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "message": { "type": "string" } } }, "request_id": { "type": "string" } } } } } }, "201": { "description": "Brief generated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "brief_id": { "type": "string", "format": "uuid" }, "analysis_id": { "type": "string", "format": "uuid" }, "topic": { "type": "string" }, "message": { "type": "string" } } }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Analysis is not in 'ready' status" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/competitive-analysis/locations": { "get": { "operationId": "searchLocations", "summary": "Search locations", "description": "Search for geographic locations to use when starting a competitive analysis. Returns location codes, names, and types.", "tags": [ "Competitive Analysis" ], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2 }, "description": "Search query (minimum 2 characters)" } ], "responses": { "200": { "description": "Location search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "locations": { "type": "array", "items": { "type": "object", "properties": { "location_code": { "type": "integer" }, "location_name": { "type": "string" }, "location_type": { "type": "string" } } } } } }, "request_id": { "type": "string" } } } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/legacy/process_serp": { "post": { "operationId": "legacyProcessSerp", "summary": "Process SERP (Legacy)", "description": "Legacy endpoint for SERP processing. Search Google and process results.", "tags": [ "Legacy" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string" }, "count": { "type": "integer", "default": 10 }, "location": { "type": "string", "description": "Search location" }, "language": { "type": "string", "description": "Language code" } } } } } }, "responses": { "200": { "description": "SERP results" } } } }, "/legacy/process_url": { "post": { "operationId": "legacyProcessUrl", "summary": "Process URL (Legacy)", "description": "Legacy endpoint for URL processing. Extract content from a URL.", "tags": [ "Legacy" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" }, "only_main_content": { "type": "boolean", "default": true, "description": "Extract only main content, excluding navigation and sidebars" } } } } } }, "responses": { "200": { "description": "Extracted content" } } } }, "/legacy/get_document_id": { "post": { "operationId": "legacyGetDocument", "summary": "Get document by ID (Legacy)", "description": "Legacy endpoint to get a document by ID.", "tags": [ "Legacy" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "doc_id" ], "properties": { "doc_id": { "type": "string", "description": "The document ID (content or brief UUID)" } } } } } }, "responses": { "200": { "description": "Document data", "content": { "application/json": { "schema": { "type": "object", "properties": { "doc_id": { "type": "string" }, "type": { "type": "string", "enum": [ "content", "brief" ] }, "title": { "type": "string" }, "text": { "type": "string", "nullable": true, "description": "Content body (content type only)" }, "status": { "type": "string" }, "word_count": { "type": "integer", "nullable": true }, "meta_title": { "type": "string", "nullable": true }, "meta_description": { "type": "string", "nullable": true }, "target_keywords": { "type": "array", "items": { "type": "string" } }, "content_type": { "type": "string", "nullable": true, "description": "Brief content type (brief type only)" }, "outline": { "type": "array", "nullable": true, "description": "Brief outline (brief type only)" }, "target_word_count": { "type": "integer", "nullable": true, "description": "Brief target word count (brief type only)" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "nullable": true }, "published_at": { "type": "string", "format": "date-time", "nullable": true } } } } } } } } }, "/legacy/get_documents_email": { "post": { "operationId": "legacyGetDocumentsByEmail", "summary": "Get documents by email (Legacy)", "description": "Legacy endpoint to get all documents by user email.", "tags": [ "Legacy" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "description": "User email to look up documents for" } } } } } }, "responses": { "200": { "description": "List of documents", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "user": { "type": "object", "properties": { "id": { "type": "string" }, "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true } } }, "documents": { "type": "array", "items": { "type": "object", "properties": { "doc_id": { "type": "string" }, "type": { "type": "string", "enum": [ "content", "brief" ] }, "title": { "type": "string" }, "status": { "type": "string" }, "word_count": { "type": "integer", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } } } }, "total": { "type": "integer" } } } } } } } } }, "/rules": { "get": { "operationId": "listRules", "summary": "List rules", "description": "Retrieve all content rules for your organization, including system rules and custom rules.", "tags": [ "Rules" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } } ], "responses": { "200": { "description": "List of rules", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedRules" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/rules/{id}": { "get": { "operationId": "getRule", "summary": "Get rule", "description": "Retrieve a single content rule by ID.", "tags": [ "Rules" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Rule ID" } ], "responses": { "200": { "description": "Rule details", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RuleDetail" }, "request_id": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "deleteRule", "summary": "Delete rule", "description": "Delete a rule. System rules cannot be deleted.", "tags": [ "Rules" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Rule ID" } ], "responses": { "200": { "description": "Rule deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } }, "request_id": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "System rule cannot be deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/rule-sets": { "get": { "operationId": "listRuleSets", "summary": "List rule sets", "description": "Retrieve all rule sets for your organization, optionally filtered by site.", "tags": [ "Rule Sets" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } }, { "name": "site_id", "in": "query", "description": "Filter rule sets by site", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "List of rule sets", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedRuleSets" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/rule-sets/{id}": { "get": { "operationId": "getRuleSet", "summary": "Get rule set", "description": "Retrieve a single rule set by ID, including full rule details.", "tags": [ "Rule Sets" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Rule set ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Rule set details", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RuleSetDetail" }, "request_id": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "operationId": "deleteRuleSet", "summary": "Delete rule set", "description": "Delete a rule set. System rule sets cannot be deleted.", "tags": [ "Rule Sets" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Rule set ID" } ], "responses": { "200": { "description": "Rule set deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } }, "request_id": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "System rule set cannot be deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/playbooks": { "get": { "operationId": "listPlaybooks", "summary": "List playbooks", "description": "Retrieve playbooks for your organization.", "tags": [ "Playbooks" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "description": "Page number" }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 }, "description": "Items per page" }, { "name": "site_id", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Filter by site ID" } ], "responses": { "200": { "description": "Paginated list of playbooks", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PlaybookSummary" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/playbooks/{id}": { "get": { "operationId": "getPlaybook", "summary": "Get playbook", "description": "Retrieve a single playbook by ID.", "tags": [ "Playbooks" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Playbook ID" } ], "responses": { "200": { "description": "Playbook details", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Playbook" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "deletePlaybook", "summary": "Delete playbook", "description": "Delete a playbook. System playbooks cannot be deleted.", "tags": [ "Playbooks" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Playbook ID" } ], "responses": { "200": { "description": "Playbook deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } }, "request_id": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "System playbook cannot be deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/templates": { "get": { "operationId": "listTemplates", "summary": "List templates", "description": "Retrieve all content templates in your organization. Supports pagination and filtering by content type.", "tags": [ "Templates" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } }, { "name": "content_type", "in": "query", "description": "Filter templates by content type", "schema": { "type": "string", "enum": [ "blog", "guide", "landing", "product", "comparison" ] } } ], "responses": { "200": { "description": "List of templates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedTemplates" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/templates/{id}": { "get": { "operationId": "getTemplate", "summary": "Get template", "description": "Retrieve a specific content template by ID.", "tags": [ "Templates" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Template ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Template details", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Template" }, "request_id": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "deleteTemplate", "summary": "Delete template", "description": "Delete a template. System templates cannot be deleted.", "tags": [ "Templates" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Template ID" } ], "responses": { "200": { "description": "Template deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } }, "request_id": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "System template cannot be deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/cms/posts": { "get": { "operationId": "listCmsPosts", "summary": "List CMS posts", "description": "Retrieve CMS posts for a site with optional filtering by status and type.", "tags": [ "CMS" ], "parameters": [ { "name": "site_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Site ID" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "draft", "published", "scheduled" ] } }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "blog_post", "page" ] } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } } ], "responses": { "200": { "description": "Paginated list of CMS posts", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CmsPost" } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "page_size": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "operationId": "createCmsPost", "summary": "Create a CMS post", "description": "Create a new post in Frase CMS. CMS must be enabled on the site.", "tags": [ "CMS" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CmsPostInput" } } } }, "responses": { "201": { "description": "Post created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CmsPost" } } } } } }, "422": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/cms/posts/{id}": { "get": { "operationId": "getCmsPost", "summary": "Get a CMS post", "description": "Retrieve a single CMS post by ID.", "tags": [ "CMS" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Post ID" } ], "responses": { "200": { "description": "Post details", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CmsPost" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "operationId": "updateCmsPost", "summary": "Update a CMS post", "description": "Update an existing CMS post. Only provided fields are updated.", "tags": [ "CMS" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Post ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CmsPostUpdateInput" } } } }, "responses": { "200": { "description": "Post updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CmsPost" } } } } } }, "422": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "operationId": "deleteCmsPost", "summary": "Delete a CMS post", "description": "Delete a CMS post by ID.", "tags": [ "CMS" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Post ID" } ], "responses": { "200": { "description": "Post deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/cms/posts/{id}/publish": { "post": { "operationId": "publishCmsPost", "summary": "Publish a CMS post", "description": "Transition a draft post to published status.", "tags": [ "CMS" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Post ID" } ], "responses": { "200": { "description": "Post published", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CmsPost" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/cms/posts/{id}/unpublish": { "post": { "operationId": "unpublishCmsPost", "summary": "Unpublish a CMS post", "description": "Transition a published post back to draft status.", "tags": [ "CMS" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Post ID" } ], "responses": { "200": { "description": "Post unpublished", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CmsPost" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/cms/posts/import": { "post": { "operationId": "importCmsPosts", "summary": "Bulk import CMS posts", "description": "Start an asynchronous bulk import of up to 100 posts. Returns a job ID that can be polled for progress. CMS must be enabled on the target site.", "tags": [ "CMS" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "site_id", "posts" ], "properties": { "site_id": { "type": "string", "format": "uuid" }, "posts": { "type": "array", "maxItems": 100, "items": { "type": "object", "required": [ "title", "content" ], "properties": { "title": { "type": "string", "maxLength": 500 }, "content": { "type": "string", "maxLength": 512000 }, "slug": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "published", "scheduled" ] }, "type": { "type": "string", "enum": [ "blog_post", "page" ] }, "excerpt": { "type": "string" }, "featured_image": { "type": "string", "format": "uri" }, "seo_title": { "type": "string" }, "seo_description": { "type": "string" }, "focus_keyword": { "type": "string" }, "canonical_url": { "type": "string", "format": "uri" }, "published_at": { "type": "string", "format": "date-time" }, "schema_markup": { "type": "object", "description": "JSON-LD structured data for the post. Must include `@context` and `@type`. Additional properties depend on the chosen schema type. See [schema.org](https://schema.org) for full type definitions.", "properties": { "@context": { "type": "string", "default": "https://schema.org", "description": "Schema.org context URL. Almost always `https://schema.org`." }, "@type": { "type": "string", "description": "The schema.org type for this content.", "enum": [ "Article", "BlogPosting", "NewsArticle", "FAQPage", "HowTo", "TechArticle", "WebPage" ] }, "headline": { "type": "string", "description": "The headline of the article. Recommended for Article, BlogPosting, NewsArticle.", "maxLength": 110 }, "description": { "type": "string", "description": "A short description or summary of the content." }, "author": { "oneOf": [ { "type": "object", "description": "Author as a Person or Organization.", "properties": { "@type": { "type": "string", "enum": [ "Person", "Organization" ] }, "name": { "type": "string" }, "url": { "type": "string", "format": "uri" } } }, { "type": "array", "description": "Multiple authors.", "items": { "type": "object", "properties": { "@type": { "type": "string", "enum": [ "Person", "Organization" ] }, "name": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } } ] }, "datePublished": { "type": "string", "format": "date", "description": "Original publication date in ISO 8601 format (e.g., `2026-04-16`)." }, "dateModified": { "type": "string", "format": "date", "description": "Last modification date in ISO 8601 format." }, "image": { "oneOf": [ { "type": "string", "format": "uri" }, { "type": "object", "properties": { "@type": { "type": "string", "enum": [ "ImageObject" ] }, "url": { "type": "string", "format": "uri" }, "width": { "type": "integer" }, "height": { "type": "integer" } } } ], "description": "Primary image. Can be a URL string or an ImageObject." }, "publisher": { "type": "object", "description": "The publisher of the content.", "properties": { "@type": { "type": "string", "enum": [ "Organization" ] }, "name": { "type": "string" }, "logo": { "type": "object", "properties": { "@type": { "type": "string", "enum": [ "ImageObject" ] }, "url": { "type": "string", "format": "uri" } } } } }, "mainEntity": { "description": "Primary entity of the page. Used by FAQPage (array of Question) and HowTo (HowToStep array).", "oneOf": [ { "type": "array", "description": "For FAQPage: array of Question objects.", "items": { "type": "object", "properties": { "@type": { "type": "string", "enum": [ "Question" ] }, "name": { "type": "string", "description": "The question text." }, "acceptedAnswer": { "type": "object", "properties": { "@type": { "type": "string", "enum": [ "Answer" ] }, "text": { "type": "string", "description": "The answer text." } } } } } }, { "type": "object" } ] }, "step": { "type": "array", "description": "For HowTo: ordered list of steps.", "items": { "type": "object", "properties": { "@type": { "type": "string", "enum": [ "HowToStep" ] }, "name": { "type": "string", "description": "Step title." }, "text": { "type": "string", "description": "Step instructions." }, "image": { "type": "string", "format": "uri" } } } } }, "additionalProperties": true }, "meta": { "type": "object" } } } }, "options": { "type": "object", "properties": { "on_conflict": { "type": "string", "enum": [ "skip", "overwrite" ], "default": "skip", "description": "Behavior when a post with the same slug already exists" }, "default_status": { "type": "string", "enum": [ "draft", "published", "scheduled" ], "default": "draft", "description": "Default status for posts that don't specify one" } } } } } } } }, "responses": { "202": { "description": "Import job queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "queued" ] }, "posts_queued": { "type": "integer" }, "site_id": { "type": "string", "format": "uuid" } } } } } } } }, "422": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/cms/posts/import/{jobId}": { "get": { "operationId": "getCmsImportJobStatus", "summary": "Get import job status", "description": "Check the progress of a bulk import job. Poll this endpoint until status is `completed` or `failed`.", "tags": [ "CMS" ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Import job ID" } ], "responses": { "200": { "description": "Import job status", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CmsImportJob" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-KEY", "description": "API key for authentication. Get your key from Settings > API Keys." } }, "schemas": { "TemplateSectionDef": { "type": "object", "required": [ "heading", "level" ], "description": "A section definition within a template outline.", "properties": { "heading": { "type": "string", "minLength": 1, "description": "The section heading text" }, "level": { "type": "integer", "minimum": 1, "maximum": 6, "description": "Heading level (1-6)" }, "keyPoints": { "type": "array", "items": { "type": "string" }, "default": [], "description": "Key points to cover in this section" }, "suggestedWordCount": { "type": "integer", "minimum": 0, "default": 200, "description": "Suggested word count for this section" }, "isRequired": { "type": "boolean", "default": true, "description": "Whether this section is required" }, "generationMode": { "type": "string", "enum": [ "ai", "manual" ], "description": "Whether AI generates this section or user provides content" } } }, "BoilerplateBlock": { "type": "object", "required": [ "id", "position", "content", "label" ], "description": "A reusable content block that can be inserted at specific positions in generated content.", "properties": { "id": { "type": "string", "minLength": 1, "description": "Unique identifier for the block" }, "position": { "type": "string", "enum": [ "before_section", "after_section", "header", "footer" ], "description": "Where to insert the block" }, "anchorSectionHeading": { "type": "string", "description": "Section heading to anchor to (for before_section/after_section positions)" }, "content": { "type": "string", "maxLength": 50000, "description": "The boilerplate content (max 50,000 characters)" }, "label": { "type": "string", "minLength": 1, "description": "Display label for the block" } } }, "TemplateFieldDefaults": { "type": "object", "description": "Default field values applied when the template is used.", "properties": { "targetWordCount": { "type": "integer", "minimum": 0, "description": "Default target word count" }, "metaTitleFormat": { "type": "string", "description": "Default meta title format" }, "suggestedTone": { "type": "string", "description": "Default suggested tone" }, "targetLanguage": { "type": "string", "description": "Default target language" }, "targetCountry": { "type": "string", "description": "Default target country" } } }, "Template": { "type": "object", "description": "A content template defining outline structure, boilerplate blocks, and field defaults.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "content_type": { "type": "string", "enum": [ "blog", "guide", "landing", "product", "comparison" ], "nullable": true }, "outline_sections": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateSectionDef" } }, "section_count": { "type": "integer", "description": "Number of sections in the outline" }, "total_word_count": { "type": "integer", "description": "Sum of suggested word counts across all sections" }, "boilerplate_blocks": { "type": "array", "items": { "$ref": "#/components/schemas/BoilerplateBlock" }, "nullable": true }, "field_defaults": { "allOf": [ { "$ref": "#/components/schemas/TemplateFieldDefaults" } ], "nullable": true }, "source_type": { "type": "string", "nullable": true, "description": "Source from which this template was extracted" }, "is_system": { "type": "boolean", "description": "Whether this is a system-provided template" }, "is_default": { "type": "boolean", "description": "Whether this is the default template" }, "is_enabled": { "type": "boolean", "description": "Whether this template is enabled" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } } }, "PaginatedTemplates": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Template" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } }, "ContentOutlineSection": { "type": "object", "required": [ "heading", "level" ], "description": "A section in the content outline. Each section represents a heading that will be generated as a content section.", "properties": { "heading": { "type": "string", "maxLength": 500, "description": "The section heading text" }, "level": { "type": "integer", "minimum": 1, "maximum": 4, "description": "Heading level (1=H1, 2=H2, 3=H3, 4=H4)" }, "key_points": { "type": "array", "items": { "type": "string" }, "default": [], "description": "Key points to cover in this section" }, "suggested_word_count": { "type": "integer", "minimum": 0, "default": 200, "description": "Suggested word count for this section" }, "generation_mode": { "type": "string", "enum": [ "ai", "manual" ], "default": "ai", "description": "Whether AI generates this section ('ai') or user provides content ('manual')" } } }, "PaginatedSites": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Site" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } }, "Site": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "domain": { "type": "string" }, "name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } } }, "CreateSiteInput": { "type": "object", "required": [ "name", "domain" ], "properties": { "name": { "type": "string", "description": "Display name for the site" }, "domain": { "type": "string", "description": "Domain name (e.g., example.com). Protocol and trailing slashes are automatically removed." }, "description": { "type": "string", "description": "Optional description of the site" } } }, "SiteCreated": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "domain": { "type": "string" }, "description": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "request_id": { "type": "string" } } }, "PaginatedContent": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ContentSummary" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } }, "ContentSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "generating", "review", "published", "archived" ] }, "word_count": { "type": "integer" }, "site_id": { "type": "string", "format": "uuid", "nullable": true }, "is_monitored": { "type": "boolean", "description": "True when the article is under Content Guard monitoring." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Content": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "brief_id": { "type": "string", "format": "uuid", "nullable": true }, "site_id": { "type": "string", "format": "uuid", "nullable": true }, "project_id": { "type": "string", "format": "uuid", "nullable": true }, "folder_id": { "type": "string", "format": "uuid", "nullable": true }, "title": { "type": "string", "nullable": true }, "slug": { "type": "string", "nullable": true }, "type": { "type": "string", "nullable": true }, "body": { "type": "string", "nullable": true }, "language": { "type": "string", "nullable": true, "description": "ISO 639-1 language code (e.g., 'en', 'de')" }, "country": { "type": "string", "nullable": true, "description": "ISO 3166-1 country code (e.g., 'US', 'DE')" }, "meta_title": { "type": "string", "nullable": true }, "meta_description": { "type": "string", "nullable": true }, "target_keywords": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "draft", "generating", "review", "published", "archived" ] }, "word_count": { "type": "integer", "nullable": true }, "eeat_score": { "type": "integer", "nullable": true, "description": "E-E-A-T score (0-100)" }, "geo_score": { "type": "integer", "nullable": true, "description": "GEO optimization score (0-100)" }, "seo_score": { "type": "integer", "nullable": true, "description": "SEO score (0-100)" }, "quotability_score": { "type": "integer", "nullable": true, "description": "Quotability score (0-100)" }, "ai_citation_score": { "type": "integer", "nullable": true, "description": "AI citation readiness score (0-100)" }, "eeat_breakdown": { "$ref": "#/components/schemas/EeatBreakdown" }, "geo_breakdown": { "$ref": "#/components/schemas/GeoBreakdown" }, "seo_breakdown": { "$ref": "#/components/schemas/SeoBreakdown" }, "featured_image": { "type": "string", "nullable": true, "description": "URL of the featured image" }, "hero_image_prompt": { "type": "string", "nullable": true, "description": "AI prompt used to generate hero image" }, "published_url": { "type": "string", "nullable": true }, "published_at": { "type": "string", "format": "date-time", "nullable": true }, "is_monitored": { "type": "boolean", "description": "True when the article is under Content Guard monitoring." }, "monitored_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp monitoring was first enabled for this article." }, "scheduled_at": { "type": "string", "format": "date-time", "nullable": true }, "schema_markup": { "type": "object", "nullable": true, "description": "JSON-LD schema markup" }, "schema_types": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "Schema types (e.g., 'Article', 'FAQPage')" }, "progress_details": { "$ref": "#/components/schemas/ContentProgressDetails" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } } }, "EeatBreakdown": { "type": "object", "nullable": true, "description": "E-E-A-T score breakdown", "properties": { "experience": { "type": "number", "nullable": true }, "expertise": { "type": "number", "nullable": true }, "authority": { "type": "number", "nullable": true }, "trust": { "type": "number", "nullable": true } } }, "GeoBreakdown": { "type": "object", "nullable": true, "description": "GEO score breakdown", "properties": { "quotability": { "type": "number", "nullable": true }, "structure": { "type": "number", "nullable": true }, "definitions": { "type": "number", "nullable": true }, "takeaways": { "type": "number", "nullable": true } } }, "SeoBreakdown": { "type": "object", "nullable": true, "description": "SEO score breakdown", "properties": { "keywords": { "type": "number", "nullable": true }, "meta": { "type": "number", "nullable": true }, "structure": { "type": "number", "nullable": true }, "readability": { "type": "number", "nullable": true } } }, "ContentProgressDetails": { "type": "object", "nullable": true, "description": "Progress details for content generation", "properties": { "phase": { "type": "string", "enum": [ "researching", "writing", "scoring", "complete", "failed", "canceled" ] }, "phase_percent": { "type": "integer", "description": "Progress within current phase (0-100)" }, "substep": { "type": "string", "description": "Current substep description" }, "current_section": { "type": "string" }, "completed_sections": { "type": "array", "items": { "type": "string" } }, "word_count": { "type": "integer" }, "total_sections": { "type": "integer" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string" } } } }, "citation_count": { "type": "integer" }, "error": { "type": "string" } } }, "ContentStatus": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "generating", "draft", "review", "published" ] }, "brief_id": { "type": "string", "format": "uuid", "nullable": true }, "brief_topic": { "type": "string", "nullable": true }, "generation_state": { "type": "object", "properties": { "is_generating": { "type": "boolean" }, "is_draft": { "type": "boolean" }, "is_review": { "type": "boolean" }, "is_published": { "type": "boolean" }, "estimated_seconds_remaining": { "type": "integer", "nullable": true } } }, "metrics": { "type": "object", "properties": { "word_count": { "type": "integer", "nullable": true } } }, "timestamps": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "nullable": true }, "published_at": { "type": "string", "format": "date-time", "nullable": true } } } } }, "ContentExport": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "body": { "type": "string" }, "status": { "type": "string" }, "word_count": { "type": "integer" }, "meta": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" } } }, "target_keywords": { "type": "array", "items": { "type": "string" } }, "brief_id": { "type": "string", "format": "uuid", "nullable": true }, "site_id": { "type": "string", "format": "uuid", "nullable": true }, "project_id": { "type": "string", "format": "uuid", "nullable": true }, "folder_id": { "type": "string", "format": "uuid", "nullable": true }, "language": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "eeat_score": { "type": "integer", "nullable": true }, "geo_score": { "type": "integer", "nullable": true }, "seo_score": { "type": "integer", "nullable": true }, "ai_citation_score": { "type": "integer", "nullable": true }, "eeat_breakdown": { "$ref": "#/components/schemas/EeatBreakdown" }, "geo_breakdown": { "$ref": "#/components/schemas/GeoBreakdown" }, "seo_breakdown": { "$ref": "#/components/schemas/SeoBreakdown" }, "published_url": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "nullable": true }, "published_at": { "type": "string", "format": "date-time", "nullable": true }, "scheduled_at": { "type": "string", "format": "date-time", "nullable": true }, "schema_markup": { "type": "object", "nullable": true }, "schema_types": { "type": "array", "items": { "type": "string" }, "nullable": true }, "export_format": { "type": "string" }, "exported_at": { "type": "string", "format": "date-time" } } }, "PaginatedResearch": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ResearchSummary" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } }, "ResearchSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "query": { "type": "string" }, "status": { "type": "string" }, "type": { "type": "string" }, "language": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "site_id": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "Research": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "query": { "type": "string" }, "type": { "type": "string", "enum": [ "general", "topic", "competitor", "gap", "serp" ], "nullable": true }, "status": { "type": "string", "enum": [ "pending", "researching", "analyzing", "completed", "failed" ], "nullable": true }, "depth": { "type": "string", "nullable": true }, "summary": { "type": "string", "nullable": true }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/ResearchFinding" } }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/ResearchSource" } }, "site_id": { "type": "string", "format": "uuid", "nullable": true }, "project_id": { "type": "string", "format": "uuid", "nullable": true }, "language": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "progress": { "type": "integer", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "data": { "type": "object", "nullable": true, "description": "Type-specific structured research data. Shape depends on the research type. Null for legacy research sessions.", "properties": { "keywords": { "type": "array", "description": "Keywords with metrics (type=general)", "items": { "type": "object", "properties": { "keyword": { "type": "string" }, "search_volume": { "type": "integer" }, "difficulty": { "type": "string", "enum": [ "Low", "Medium", "High" ] }, "cpc": { "type": "number" }, "intent": { "type": "string", "nullable": true }, "category": { "type": "string" } } } }, "serp_results": { "type": "array", "description": "SERP competitor analysis (type=general, gap)", "items": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string" }, "domain": { "type": "string" }, "rank": { "type": "integer" }, "word_count": { "type": "integer" }, "is_own_site": { "type": "boolean" }, "is_tracked_competitor": { "type": "boolean" }, "headings": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "text": { "type": "string" } } } } } } }, "evidence": { "type": "array", "description": "Evidence items (type=general)", "items": { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "stat", "fact", "quote" ] }, "source": { "type": "string", "nullable": true } } } }, "sources": { "type": "array", "description": "Sources found (type=general)", "items": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string" }, "domain": { "type": "string" } } } }, "content_gaps": { "type": "array", "description": "Content gaps (type=gap, general)", "items": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "impact": { "type": "string", "enum": [ "high", "medium", "low" ] }, "competitors_covering": { "type": "integer" } } } }, "competitors": { "type": "array", "description": "Competitor analysis (type=competitor)", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "url": { "type": "string" }, "title": { "type": "string" }, "rank": { "type": "integer" }, "word_count": { "type": "integer" }, "headings": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "text": { "type": "string" } } } } } } }, "topic_directions": { "type": "array", "description": "Topic exploration directions (type=topic)", "items": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "angle": { "type": "string" }, "estimated_difficulty": { "type": "string", "enum": [ "Low", "Medium", "High" ] } } } }, "sub_topics": { "type": "array", "description": "Sub-topic opportunities (type=topic)", "items": { "type": "object", "properties": { "topic": { "type": "string" }, "relevance": { "type": "number" }, "search_volume": { "type": "integer" } } } }, "keyword_clusters": { "type": "array", "description": "Keyword clusters (type=topic)", "items": { "type": "object", "properties": { "cluster_name": { "type": "string" }, "keywords": { "type": "array", "items": { "type": "string" } }, "total_volume": { "type": "integer" } } } } } } } }, "ResearchFinding": { "type": "object", "properties": { "title": { "type": "string" }, "content": { "type": "string" }, "relevance": { "type": "number" }, "source_urls": { "type": "array", "items": { "type": "string" } } } }, "ResearchSource": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string" }, "snippet": { "type": "string" }, "domain": { "type": "string" } } }, "ResearchExport": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "query": { "type": "string" }, "type": { "type": "string" }, "depth": { "type": "string" }, "status": { "type": "string" }, "summary": { "type": "string" }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/ResearchFinding" } }, "topic_clusters": { "type": "array", "items": { "type": "object" } }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/ResearchSource" } }, "language": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "export_format": { "type": "string" }, "exported_at": { "type": "string", "format": "date-time" } } }, "AIVisibilityOverview": { "type": "object", "properties": { "overview": { "type": "object", "properties": { "total_prompts": { "type": "integer" }, "avg_visibility_score": { "type": "number", "nullable": true }, "total_checks": { "type": "integer" }, "total_mentions": { "type": "integer" }, "total_citations": { "type": "integer" }, "period_days": { "type": "integer" } } }, "platform_breakdown": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "checks": { "type": "integer" }, "mentions": { "type": "integer" }, "citations": { "type": "integer" }, "mention_rate": { "type": "integer", "description": "Mention rate as percentage (0-100)" }, "citation_rate": { "type": "integer", "description": "Citation rate as percentage (0-100)" } } } }, "prompts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "prompt": { "type": "string" }, "category": { "type": "string", "nullable": true }, "brand_name": { "type": "string" }, "platforms": { "type": "array", "items": { "type": "string" } }, "visibility_score": { "type": "number", "nullable": true }, "is_cited": { "type": "boolean" }, "is_visible": { "type": "boolean" }, "status": { "type": "string", "enum": [ "cited", "visible", "not_visible" ] }, "last_tracked_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } } }, "daily_trend": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "visibility_score": { "type": "number", "nullable": true }, "total_checks": { "type": "integer", "nullable": true }, "mentions": { "type": "integer", "nullable": true }, "citations": { "type": "integer", "nullable": true } } } } } }, "SERPAnalysis": { "type": "object", "properties": { "keyword": { "type": "string" }, "search_parameters": { "type": "object", "properties": { "location": { "type": "string" }, "country_code": { "type": "string" }, "language_code": { "type": "string" }, "num_results": { "type": "integer" } } }, "search_info": { "type": "object", "properties": { "total_results": { "type": "integer", "nullable": true }, "time_taken": { "type": "number", "nullable": true } } }, "ai_overview": { "type": "object", "nullable": true, "properties": { "text": { "type": "string" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "snippet": { "type": "string", "nullable": true } } } } } }, "organic_results": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "integer" }, "title": { "type": "string" }, "url": { "type": "string" }, "snippet": { "type": "string" } } } }, "people_also_ask": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "integer" }, "question": { "type": "string" }, "snippet": { "type": "string", "nullable": true }, "source_url": { "type": "string", "nullable": true } } } }, "related_searches": { "type": "array", "items": { "type": "string" } } } }, "WebhookWithSecret": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "is_active": { "type": "boolean" }, "secret": { "type": "string", "description": "Only returned on creation. Store securely." }, "created_at": { "type": "string", "format": "date-time" } } }, "JobStatus": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "audit", "research", "content", "brief", "optimization", "atomization" ] }, "status": { "type": "string" }, "progress": { "type": "integer" }, "error": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time" }, "metadata": { "type": "object" } } }, "Rule": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "condition_type": { "type": "string", "enum": [ "score_threshold", "term_compliance", "verify_chips", "word_count", "meta_required", "link_count", "section_required", "regex_pattern" ] }, "config": { "type": "object", "description": "Rule configuration object, structure varies by condition_type" }, "severity": { "type": "string", "enum": [ "error", "warning", "info" ] }, "fix_hint": { "type": "string", "nullable": true }, "is_system": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } }, "RuleDetail": { "type": "object", "description": "Rule with additional detail fields including updated_at", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "condition_type": { "type": "string", "enum": [ "score_threshold", "term_compliance", "verify_chips", "word_count", "meta_required", "link_count", "section_required", "regex_pattern" ] }, "config": { "type": "object", "description": "Rule configuration object, structure varies by condition_type" }, "severity": { "type": "string", "enum": [ "error", "warning", "info" ] }, "fix_hint": { "type": "string", "nullable": true }, "is_system": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } } }, "PaginatedRules": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Rule" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } }, "Playbook": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "steps": { "type": "array", "items": { "type": "object" } }, "step_count": { "type": "integer" }, "estimated_minutes": { "type": "integer", "nullable": true }, "is_system": { "type": "boolean" }, "is_enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } } }, "PlaybookSummary": { "type": "object", "description": "Playbook as returned in list responses", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "steps": { "type": "array", "items": { "type": "object" } }, "step_count": { "type": "integer" }, "estimated_minutes": { "type": "integer", "nullable": true }, "is_system": { "type": "boolean" }, "is_enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } }, "Pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "page_size": { "type": "integer" }, "total": { "type": "integer" }, "has_more": { "type": "boolean" } } }, "RuleSetRuleSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "condition_type": { "type": "string" }, "severity": { "type": "string" }, "sort_order": { "type": "integer" } } }, "RuleSetRuleDetail": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "condition_type": { "type": "string" }, "config": { "type": "object", "nullable": true }, "severity": { "type": "string" }, "fix_hint": { "type": "string", "nullable": true }, "is_system": { "type": "boolean" }, "sort_order": { "type": "integer" } } }, "RuleSetSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "is_system": { "type": "boolean" }, "is_enabled": { "type": "boolean" }, "rule_count": { "type": "integer" }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/RuleSetRuleSummary" } }, "created_at": { "type": "string", "format": "date-time" } } }, "RuleSetDetail": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "is_system": { "type": "boolean" }, "is_enabled": { "type": "boolean" }, "rule_count": { "type": "integer" }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/RuleSetRuleDetail" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } } }, "PaginatedRuleSets": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RuleSetSummary" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "doc_url": { "type": "string" } } }, "request_id": { "type": "string" } } }, "CmsPost": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "site_id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "type": { "type": "string", "enum": [ "blog_post", "page" ] }, "title": { "type": "string" }, "content": { "type": "string", "description": "HTML content" }, "excerpt": { "type": "string", "nullable": true }, "featured_image": { "type": "string", "format": "uri", "nullable": true }, "seo_title": { "type": "string", "nullable": true }, "seo_description": { "type": "string", "nullable": true }, "focus_keyword": { "type": "string", "nullable": true }, "canonical_url": { "type": "string", "format": "uri", "nullable": true }, "schema_markup": { "type": "object", "description": "JSON-LD structured data for the post. Must include `@context` and `@type`. Additional properties depend on the chosen schema type. See [schema.org](https://schema.org) for full type definitions.", "properties": { "@context": { "type": "string", "default": "https://schema.org", "description": "Schema.org context URL. Almost always `https://schema.org`." }, "@type": { "type": "string", "description": "The schema.org type for this content.", "enum": [ "Article", "BlogPosting", "NewsArticle", "FAQPage", "HowTo", "TechArticle", "WebPage" ] }, "headline": { "type": "string", "description": "The headline of the article. Recommended for Article, BlogPosting, NewsArticle.", "maxLength": 110 }, "description": { "type": "string", "description": "A short description or summary of the content." }, "author": { "oneOf": [ { "type": "object", "description": "Author as a Person or Organization.", "properties": { "@type": { "type": "string", "enum": [ "Person", "Organization" ] }, "name": { "type": "string" }, "url": { "type": "string", "format": "uri" } } }, { "type": "array", "description": "Multiple authors.", "items": { "type": "object", "properties": { "@type": { "type": "string", "enum": [ "Person", "Organization" ] }, "name": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } } ] }, "datePublished": { "type": "string", "format": "date", "description": "Original publication date in ISO 8601 format (e.g., `2026-04-16`)." }, "dateModified": { "type": "string", "format": "date", "description": "Last modification date in ISO 8601 format." }, "image": { "oneOf": [ { "type": "string", "format": "uri" }, { "type": "object", "properties": { "@type": { "type": "string", "enum": [ "ImageObject" ] }, "url": { "type": "string", "format": "uri" }, "width": { "type": "integer" }, "height": { "type": "integer" } } } ], "description": "Primary image. Can be a URL string or an ImageObject." }, "publisher": { "type": "object", "description": "The publisher of the content.", "properties": { "@type": { "type": "string", "enum": [ "Organization" ] }, "name": { "type": "string" }, "logo": { "type": "object", "properties": { "@type": { "type": "string", "enum": [ "ImageObject" ] }, "url": { "type": "string", "format": "uri" } } } } }, "mainEntity": { "description": "Primary entity of the page. Used by FAQPage (array of Question) and HowTo (HowToStep array).", "oneOf": [ { "type": "array", "description": "For FAQPage: array of Question objects.", "items": { "type": "object", "properties": { "@type": { "type": "string", "enum": [ "Question" ] }, "name": { "type": "string", "description": "The question text." }, "acceptedAnswer": { "type": "object", "properties": { "@type": { "type": "string", "enum": [ "Answer" ] }, "text": { "type": "string", "description": "The answer text." } } } } } }, { "type": "object" } ] }, "step": { "type": "array", "description": "For HowTo: ordered list of steps.", "items": { "type": "object", "properties": { "@type": { "type": "string", "enum": [ "HowToStep" ] }, "name": { "type": "string", "description": "Step title." }, "text": { "type": "string", "description": "Step instructions." }, "image": { "type": "string", "format": "uri" } } } } }, "additionalProperties": true, "nullable": true, "examples": [ { "@context": "https://schema.org", "@type": "BlogPosting", "headline": "How to Optimize Content for SEO", "description": "A comprehensive guide to on-page SEO optimization.", "author": { "@type": "Person", "name": "Jane Smith", "url": "https://example.com/jane" }, "publisher": { "@type": "Organization", "name": "Acme Inc.", "logo": { "@type": "ImageObject", "url": "https://example.com/logo.png" } }, "datePublished": "2026-04-16", "dateModified": "2026-04-16", "image": "https://example.com/images/seo-guide.jpg" }, { "@context": "https://schema.org", "@type": "FAQPage", "mainEntity": [ { "@type": "Question", "name": "What is SEO?", "acceptedAnswer": { "@type": "Answer", "text": "SEO stands for Search Engine Optimization, the practice of improving a website's visibility in search results." } }, { "@type": "Question", "name": "How long does SEO take?", "acceptedAnswer": { "@type": "Answer", "text": "SEO typically takes 3-6 months to show significant results." } } ] }, { "@context": "https://schema.org", "@type": "HowTo", "name": "How to Write a Content Brief", "description": "Step-by-step guide to creating an effective content brief.", "step": [ { "@type": "HowToStep", "name": "Research keywords", "text": "Use a keyword research tool to find relevant terms." }, { "@type": "HowToStep", "name": "Analyze competitors", "text": "Review top-ranking pages for your target keyword." }, { "@type": "HowToStep", "name": "Define structure", "text": "Create an outline with headings and subheadings." } ] } ] }, "status": { "type": "string", "enum": [ "draft", "published", "scheduled" ] }, "published_at": { "type": "string", "format": "date-time", "nullable": true }, "meta": { "type": "object", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "CmsPostInput": { "type": "object", "required": [ "site_id", "title", "content" ], "properties": { "site_id": { "type": "string", "format": "uuid" }, "title": { "type": "string", "maxLength": 500 }, "content": { "type": "string", "maxLength": 512000, "description": "HTML content (max 500KB)" }, "slug": { "type": "string", "description": "URL slug. Auto-generated from title if omitted." }, "status": { "type": "string", "enum": [ "draft", "published", "scheduled" ], "default": "draft" }, "type": { "type": "string", "enum": [ "blog_post", "page" ], "default": "blog_post" }, "excerpt": { "type": "string", "maxLength": 2000 }, "featured_image": { "type": "string", "format": "uri", "description": "Must be HTTPS" }, "seo_title": { "type": "string", "maxLength": 200 }, "seo_description": { "type": "string", "maxLength": 500 }, "focus_keyword": { "type": "string" }, "canonical_url": { "type": "string", "format": "uri", "description": "Must be HTTPS" }, "published_at": { "type": "string", "format": "date-time" }, "schema_markup": { "type": "object", "description": "JSON-LD structured data for the post. Must include `@context` and `@type`. Additional properties depend on the chosen schema type. See [schema.org](https://schema.org) for full type definitions.", "properties": { "@context": { "type": "string", "default": "https://schema.org", "description": "Schema.org context URL. Almost always `https://schema.org`." }, "@type": { "type": "string", "description": "The schema.org type for this content.", "enum": [ "Article", "BlogPosting", "NewsArticle", "FAQPage", "HowTo", "TechArticle", "WebPage" ] }, "headline": { "type": "string", "description": "The headline of the article. Recommended for Article, BlogPosting, NewsArticle.", "maxLength": 110 }, "description": { "type": "string", "description": "A short description or summary of the content." }, "author": { "oneOf": [ { "type": "object", "description": "Author as a Person or Organization.", "properties": { "@type": { "type": "string", "enum": [ "Person", "Organization" ] }, "name": { "type": "string" }, "url": { "type": "string", "format": "uri" } } }, { "type": "array", "description": "Multiple authors.", "items": { "type": "object", "properties": { "@type": { "type": "string", "enum": [ "Person", "Organization" ] }, "name": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } } ] }, "datePublished": { "type": "string", "format": "date", "description": "Original publication date in ISO 8601 format (e.g., `2026-04-16`)." }, "dateModified": { "type": "string", "format": "date", "description": "Last modification date in ISO 8601 format." }, "image": { "oneOf": [ { "type": "string", "format": "uri" }, { "type": "object", "properties": { "@type": { "type": "string", "enum": [ "ImageObject" ] }, "url": { "type": "string", "format": "uri" }, "width": { "type": "integer" }, "height": { "type": "integer" } } } ], "description": "Primary image. Can be a URL string or an ImageObject." }, "publisher": { "type": "object", "description": "The publisher of the content.", "properties": { "@type": { "type": "string", "enum": [ "Organization" ] }, "name": { "type": "string" }, "logo": { "type": "object", "properties": { "@type": { "type": "string", "enum": [ "ImageObject" ] }, "url": { "type": "string", "format": "uri" } } } } }, "mainEntity": { "description": "Primary entity of the page. Used by FAQPage (array of Question) and HowTo (HowToStep array).", "oneOf": [ { "type": "array", "description": "For FAQPage: array of Question objects.", "items": { "type": "object", "properties": { "@type": { "type": "string", "enum": [ "Question" ] }, "name": { "type": "string", "description": "The question text." }, "acceptedAnswer": { "type": "object", "properties": { "@type": { "type": "string", "enum": [ "Answer" ] }, "text": { "type": "string", "description": "The answer text." } } } } } }, { "type": "object" } ] }, "step": { "type": "array", "description": "For HowTo: ordered list of steps.", "items": { "type": "object", "properties": { "@type": { "type": "string", "enum": [ "HowToStep" ] }, "name": { "type": "string", "description": "Step title." }, "text": { "type": "string", "description": "Step instructions." }, "image": { "type": "string", "format": "uri" } } } } }, "additionalProperties": true }, "meta": { "type": "object" } } }, "CmsPostUpdateInput": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 500 }, "content": { "type": "string", "maxLength": 512000 }, "slug": { "type": "string" }, "type": { "type": "string", "enum": [ "blog_post", "page" ] }, "excerpt": { "type": "string", "maxLength": 2000 }, "featured_image": { "type": "string", "format": "uri" }, "seo_title": { "type": "string", "maxLength": 200 }, "seo_description": { "type": "string", "maxLength": 500 }, "focus_keyword": { "type": "string" }, "canonical_url": { "type": "string", "format": "uri" }, "schema_markup": { "type": "object", "description": "JSON-LD structured data for the post. Must include `@context` and `@type`. Additional properties depend on the chosen schema type. See [schema.org](https://schema.org) for full type definitions.", "properties": { "@context": { "type": "string", "default": "https://schema.org", "description": "Schema.org context URL. Almost always `https://schema.org`." }, "@type": { "type": "string", "description": "The schema.org type for this content.", "enum": [ "Article", "BlogPosting", "NewsArticle", "FAQPage", "HowTo", "TechArticle", "WebPage" ] }, "headline": { "type": "string", "description": "The headline of the article. Recommended for Article, BlogPosting, NewsArticle.", "maxLength": 110 }, "description": { "type": "string", "description": "A short description or summary of the content." }, "author": { "oneOf": [ { "type": "object", "description": "Author as a Person or Organization.", "properties": { "@type": { "type": "string", "enum": [ "Person", "Organization" ] }, "name": { "type": "string" }, "url": { "type": "string", "format": "uri" } } }, { "type": "array", "description": "Multiple authors.", "items": { "type": "object", "properties": { "@type": { "type": "string", "enum": [ "Person", "Organization" ] }, "name": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } } ] }, "datePublished": { "type": "string", "format": "date", "description": "Original publication date in ISO 8601 format (e.g., `2026-04-16`)." }, "dateModified": { "type": "string", "format": "date", "description": "Last modification date in ISO 8601 format." }, "image": { "oneOf": [ { "type": "string", "format": "uri" }, { "type": "object", "properties": { "@type": { "type": "string", "enum": [ "ImageObject" ] }, "url": { "type": "string", "format": "uri" }, "width": { "type": "integer" }, "height": { "type": "integer" } } } ], "description": "Primary image. Can be a URL string or an ImageObject." }, "publisher": { "type": "object", "description": "The publisher of the content.", "properties": { "@type": { "type": "string", "enum": [ "Organization" ] }, "name": { "type": "string" }, "logo": { "type": "object", "properties": { "@type": { "type": "string", "enum": [ "ImageObject" ] }, "url": { "type": "string", "format": "uri" } } } } }, "mainEntity": { "description": "Primary entity of the page. Used by FAQPage (array of Question) and HowTo (HowToStep array).", "oneOf": [ { "type": "array", "description": "For FAQPage: array of Question objects.", "items": { "type": "object", "properties": { "@type": { "type": "string", "enum": [ "Question" ] }, "name": { "type": "string", "description": "The question text." }, "acceptedAnswer": { "type": "object", "properties": { "@type": { "type": "string", "enum": [ "Answer" ] }, "text": { "type": "string", "description": "The answer text." } } } } } }, { "type": "object" } ] }, "step": { "type": "array", "description": "For HowTo: ordered list of steps.", "items": { "type": "object", "properties": { "@type": { "type": "string", "enum": [ "HowToStep" ] }, "name": { "type": "string", "description": "Step title." }, "text": { "type": "string", "description": "Step instructions." }, "image": { "type": "string", "format": "uri" } } } } }, "additionalProperties": true }, "meta": { "type": "object" } } }, "CmsImportJob": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "queued", "processing", "completed", "failed" ] }, "site_id": { "type": "string", "format": "uuid" }, "posts_queued": { "type": "integer" }, "posts_succeeded": { "type": "integer" }, "posts_failed": { "type": "integer" }, "posts_skipped": { "type": "integer" }, "errors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "index": { "type": "integer" }, "slug": { "type": "string" }, "error": { "type": "string" } } } }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true } } } }, "responses": { "Unauthorized": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "authentication_error", "code": "invalid_api_key", "message": "Invalid API key. Check that you are using the correct key.", "doc_url": "https://docs.frase.io/api/errors#invalid_api_key" }, "request_id": "req_abc123" } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The requested resource was not found.", "doc_url": "https://docs.frase.io/api/errors#resource_not_found" }, "request_id": "req_abc123" } } } }, "ValidationError": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "invalid_request_error", "code": "validation_error", "message": "The request body is invalid.", "param": "prompt_text", "doc_url": "https://docs.frase.io/api/errors#validation_error" }, "request_id": "req_abc123" } } } }, "Forbidden": { "description": "Forbidden - action not allowed on this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "invalid_request_error", "code": "forbidden", "message": "System rules cannot be modified.", "doc_url": "https://docs.frase.io/api/errors#forbidden" }, "request_id": "req_abc123" } } } }, "RateLimited": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until rate limit resets" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Rate limit exceeded. Please retry after 60 seconds.", "doc_url": "https://docs.frase.io/api/errors#rate_limit_exceeded" }, "request_id": "req_abc123" } } } } } } }