{"openapi":"3.0.3","info":{"title":"Collabraz API","version":"1.0.0","description":"Workspace API. Requires a paid plan and a workspace API key."},"servers":[{"url":"https://www.collabraz.com/api/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Workspace API key beginning with clb_live_."}}},"paths":{"/websites":{"get":{"operationId":"websites","tags":["Websites"],"summary":"List websites","description":"Retrieve the websites in your API key's workspace, including their domains, publishing mode and content counts.","parameters":[],"responses":{"200":{"description":"Successful response. Example values are illustrative.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"workspace":{"id":"workspace_example","name":"My workspace","plan":"Growth"},"total":1,"websites":[{"id":"website_example","name":"My website","slug":"my-website","subdomain":"example.collabraz.com","customDomain":null,"primaryUrl":"https://example.collabraz.com","category":"TECHNOLOGY","language":"en","destinationType":"NATIVE","publishingMode":"MANUAL_REVIEW","totalArticles":12,"totalKeywords":24,"status":"ACTIVE","createdAt":"2026-01-01T09:00:00.000Z"}]}}}},"401":{"description":"Missing, invalid, expired or revoked API key, or a workspace plan without API access.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}}}}},"/articles":{"get":{"operationId":"articles","tags":["Articles"],"summary":"List articles","description":"Browse recent articles with publishing status, metadata, word counts and live URLs. Results are ordered newest first.","parameters":[{"name":"websiteId","in":"query","required":false,"schema":{"type":"string","description":"Filter by a website in your workspace."}},{"name":"status","in":"query","required":false,"schema":{"type":"string","description":"Filter by an article status, for example PUBLISHED or DRAFT."}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1,"minimum":1,"description":"Page number. Pagination starts at 1."}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20,"minimum":1,"maximum":50,"description":"Number of results per page."}}],"responses":{"200":{"description":"Successful response. Example values are illustrative.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"page":1,"limit":10,"total":1,"totalPages":1,"articles":[{"id":"article_example","title":"A guide to content planning","slug":"content-planning","status":"DRAFT","metaDescription":"Build a practical content plan.","primaryKeyword":"content planning","wordCount":1200,"readingTimeMinutes":6,"liveUrl":null,"website":{"id":"website_example","name":"My website"},"publishedAt":null,"createdAt":"2026-01-01T09:00:00.000Z","updatedAt":"2026-01-01T09:00:00.000Z"}]}}}},"401":{"description":"Missing, invalid, expired or revoked API key, or a workspace plan without API access.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}}}}},"/articles/generate":{"post":{"operationId":"generate","tags":["Articles"],"summary":"Generate an article","description":"Start a background article-generation job for a keyword. The response contains the job and queue item IDs, not the finished article.\n\nGeneration uses your monthly article allowance. Follow progress in Content Queue. The language field is currently accepted but is not forwarded to the generation worker; configure the website language in your workspace.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["keyword"],"properties":{"keyword":{"type":"string","minLength":2,"maxLength":150,"description":"Primary keyword or article topic (2-150 characters)."},"websiteId":{"type":"string","description":"Target website ID. Defaults to your oldest active website."},"priority":{"type":"integer","default":3,"minimum":1,"maximum":5,"description":"Queue priority, from 1 to 5."},"language":{"type":"string","description":"Accepted for compatibility; currently has no effect on generation."}}},"example":{"keyword":"how to build a content calendar","priority":3}}}},"responses":{"200":{"description":"Successful response. Example values are illustrative.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"message":"Article generation initiated in the background.","jobId":"job_example","queueItemId":"queue_example","keyword":"how to build a content calendar","website":{"id":"website_example","name":"My website","subdomain":"example","customDomain":null},"status":"PROCESSING","createdAt":"2026-01-01T09:00:00.000Z"}}}},"400":{"description":"Invalid JSON, validation failure or no active website for generation.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"401":{"description":"Missing, invalid, expired or revoked API key, or a workspace plan without API access.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"402":{"description":"Article-generation allowance exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"404":{"description":"The requested website was not found in the workspace.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}}}}},"/keywords/suggest":{"post":{"operationId":"keywords","tags":["Keywords"],"summary":"Suggest keywords","description":"Generate keyword ideas for a topic in your chosen language. Suggestions are AI-generated ideas, not measured search-volume or difficulty data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["query"],"properties":{"query":{"type":"string","minLength":2,"maxLength":100,"description":"Seed keyword, niche or topic (2-100 characters)."},"language":{"type":"string","default":"en","description":"Supported language code, such as en, de, ar or ur."},"count":{"type":"integer","default":6,"minimum":1,"maximum":20,"description":"Number of suggestions to request."}}},"example":{"query":"content marketing","language":"en","count":3}}}},"responses":{"200":{"description":"Successful response. Example values are illustrative.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"query":"content marketing","language":"en","languageName":"English","total":3,"keywords":["content marketing for small businesses","how to plan a content calendar","content marketing strategy examples"]}}}},"400":{"description":"Invalid JSON, validation failure or no active website for generation.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"401":{"description":"Missing, invalid, expired or revoked API key, or a workspace plan without API access.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"500":{"description":"An AI operation failed. Review the error message before retrying.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}}}}},"/geo/audit":{"post":{"operationId":"visibility","tags":["AI visibility"],"summary":"Audit AI visibility","description":"Evaluate a query for your brand, then save the audit to your workspace. Results include mentions, citations and recommendations from the configured analysis engine.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["query"],"properties":{"query":{"type":"string","minLength":2,"maxLength":200,"description":"Query to evaluate (2-200 characters)."},"websiteId":{"type":"string","description":"Website to audit. Defaults to your oldest active website."},"targetBrand":{"type":"string","description":"Brand to evaluate. Defaults to the website name."},"engine":{"type":"string","default":"ALL","enum":["ALL","CHATGPT","PERPLEXITY","GEMINI","CLAUDE","COPILOT"],"description":"Select an analysis engine."}}},"example":{"query":"What tools help small teams plan content?","engine":"ALL"}}}},"responses":{"200":{"description":"Successful response. Example values are illustrative.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"auditId":"audit_example","query":"What tools help small teams plan content?","targetBrand":"My website","engine":"ALL","isMentioned":false,"visibilityScore":0,"rankPosition":null,"sentiment":"NEUTRAL","citedUrls":[],"competitorMentions":[],"recommendations":[],"timestamp":"2026-01-01T09:00:00.000Z"}}}},"400":{"description":"Invalid JSON, validation failure or no active website for generation.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"401":{"description":"Missing, invalid, expired or revoked API key, or a workspace plan without API access.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"404":{"description":"The requested website was not found in the workspace.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"500":{"description":"An AI operation failed. Review the error message before retrying.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}}}}}}}