{ "openapi": "3.0.3", "info": { "title": "SwooshRank Public API", "version": "1.0.0", "description": "Programmatic access to your SwooshRank articles, sites, and keywords. Authenticate with a bearer token from Settings → API & Webhooks." }, "servers": [ { "url": "https://app.swooshrank.com/api/v1" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "sr_<32hex>", "description": "API key with prefix `sr_`. Generate in Settings → API & Webhooks." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "Article": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "siteId": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "slug": { "type": "string" }, "status": { "type": "string", "enum": [ "planned", "generating", "draft", "scheduled", "published", "failed" ] }, "targetKeyword": { "type": "string", "nullable": true }, "wordCount": { "type": "integer" }, "seoScore": { "type": "integer", "nullable": true }, "publishedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "Site": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "domain": { "type": "string" }, "cms": { "type": "string" }, "language": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } }, "Keyword": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "siteId": { "type": "string", "format": "uuid" }, "keyword": { "type": "string" }, "searchVolume": { "type": "integer", "nullable": true }, "difficulty": { "type": "integer", "nullable": true }, "intent": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } } }, "ConnectAccountInput": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "google_business", "facebook_page", "tiktok", "instagram", "google_analytics", "google_search_console", "google_ads", "google_calendar", "google_contacts" ] }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "maxAccounts": { "default": 1, "type": "integer", "minimum": 1, "maximum": 20 } }, "required": [ "provider", "label" ] }, "ConnectAccountOutput": { "type": "object", "properties": { "connectUrl": { "type": "string" }, "expiresAt": { "type": "string" }, "provider": { "type": "string", "enum": [ "google_business", "facebook_page", "tiktok", "instagram", "google_analytics", "google_search_console", "google_ads", "google_calendar", "google_contacts" ] }, "label": { "type": "string" } }, "required": [ "connectUrl", "expiresAt", "provider", "label" ], "additionalProperties": false }, "ListAccountsInput": { "type": "object", "properties": {} }, "ListAccountsOutput": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "type": "object", "properties": { "accountId": { "type": "string" }, "provider": { "type": "string", "enum": [ "google_business", "facebook_page", "tiktok", "instagram", "google_analytics", "google_search_console", "google_ads", "google_calendar", "google_contacts" ] }, "label": { "type": "string" }, "name": { "nullable": true, "type": "string" }, "status": { "type": "string", "enum": [ "pending", "connected", "expired", "revoked", "pending_api_access" ] }, "locked": { "type": "boolean" }, "connectedAt": { "nullable": true, "type": "string" } }, "required": [ "accountId", "provider", "label", "name", "status", "locked", "connectedAt" ], "additionalProperties": false } }, "pendingInvites": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "provider": { "type": "string", "enum": [ "google_business", "facebook_page", "tiktok", "instagram", "google_analytics", "google_search_console", "google_ads", "google_calendar", "google_contacts" ] }, "maxAccounts": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "expiresAt": { "type": "string" } }, "required": [ "id", "label", "provider", "maxAccounts", "expiresAt" ], "additionalProperties": false } }, "billing": { "type": "object", "properties": { "connected": { "type": "number" }, "free": { "type": "number" }, "billable": { "type": "number" }, "needsPayment": { "type": "boolean" } }, "required": [ "connected", "free", "billable", "needsPayment" ], "additionalProperties": false } }, "required": [ "accounts", "pendingInvites", "billing" ], "additionalProperties": false }, "CreatePostInput": { "type": "object", "properties": { "accountId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "text": { "type": "string", "minLength": 1, "maxLength": 5000 }, "media": { "type": "object", "properties": { "imageUrl": { "type": "string", "format": "uri" } }, "required": [ "imageUrl" ] }, "link": { "type": "string", "format": "uri" } }, "required": [ "accountId", "text" ] }, "CreatePostOutput": { "type": "object", "properties": { "postId": { "type": "string" }, "permalink": { "nullable": true, "type": "string" } }, "required": [ "postId", "permalink" ], "additionalProperties": false }, "ListReviewsInput": { "type": "object", "properties": { "accountId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "cursor": { "type": "string" } }, "required": [ "accountId" ] }, "ListReviewsOutput": { "type": "object", "properties": { "reviews": { "type": "array", "items": { "type": "object", "properties": { "reviewId": { "type": "string" }, "author": { "type": "string" }, "rating": { "nullable": true, "type": "number" }, "text": { "type": "string" }, "date": { "type": "string" }, "replied": { "type": "boolean" }, "replyText": { "type": "string" } }, "required": [ "reviewId", "author", "rating", "text", "date" ], "additionalProperties": false } }, "nextCursor": { "type": "string" }, "aggregate": { "type": "object", "properties": { "ratingValue": { "type": "number" }, "reviewCount": { "type": "number" } }, "required": [ "ratingValue", "reviewCount" ], "additionalProperties": false } }, "required": [ "reviews" ], "additionalProperties": false }, "ReplyReviewInput": { "type": "object", "properties": { "accountId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "reviewId": { "type": "string", "minLength": 1 }, "text": { "type": "string", "minLength": 1, "maxLength": 4096 } }, "required": [ "accountId", "reviewId", "text" ] }, "ReplyReviewOutput": { "type": "object", "properties": { "repliedAt": { "nullable": true, "type": "string" } }, "required": [ "repliedAt" ], "additionalProperties": false }, "GetInsightsInput": { "type": "object", "properties": { "accountId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "range": { "default": "28d", "type": "string", "enum": [ "7d", "28d", "90d" ] } }, "required": [ "accountId" ] }, "GetInsightsOutput": { "type": "object", "properties": { "range": { "type": "object", "properties": { "startDate": { "type": "string" }, "endDate": { "type": "string" } }, "required": [ "startDate", "endDate" ], "additionalProperties": false }, "metrics": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "total": { "type": "number" }, "points": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "value": { "type": "number" } }, "required": [ "date", "value" ], "additionalProperties": false } } }, "required": [ "key", "label", "total", "points" ], "additionalProperties": false } } }, "required": [ "range", "metrics" ], "additionalProperties": false }, "ToolError": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input", "not_found", "not_supported", "payment_required", "subscription_inactive", "provider_auth", "provider_permission", "rate_limited", "provider_error", "transient", "unauthorized" ] }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "responses": { "Unauthorized": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Invalid or missing API key" } } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Resource not found" } } } } }, "RateLimited": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "example": { "error": "rate_limit_exceeded" } } } }, "BadRequest": { "description": "Bad request - missing or invalid parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "paths": { "/articles": { "get": { "summary": "List articles", "operationId": "listArticles", "parameters": [ { "name": "siteId", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Filter by site ID" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Pagination cursor (createdAt ISO timestamp of last item)" } ], "responses": { "200": { "description": "Paginated list of articles", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Article" } }, "cursor": { "type": "string", "nullable": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/articles/{id}": { "get": { "summary": "Get article by ID", "operationId": "getArticle", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Article", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Article" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/sites": { "get": { "summary": "List sites", "operationId": "listSites", "responses": { "200": { "description": "Sites for the authenticated org", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Site" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/sites/{id}": { "get": { "summary": "Get site by ID", "operationId": "getSite", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Site", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Site" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/keywords": { "get": { "summary": "List keywords", "operationId": "listKeywords", "parameters": [ { "name": "siteId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Keywords for the specified site", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Keyword" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/connect/accounts": { "post": { "operationId": "connectAccount", "summary": "Create a connect link", "description": "Create a single-use link for a customer's client to connect one of their social or Google Business accounts.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ConnectAccountOutput" }, "summary": { "type": "string" } }, "required": [ "data", "summary" ] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolError" }, "example": { "error": { "code": "unauthorized", "message": "Invalid or missing API key" } } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolError" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolError" } } } }, "502": { "description": "Provider error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectAccountInput" } } } } }, "get": { "operationId": "listAccounts", "summary": "List connected accounts", "description": "List every account connected so far, any pending connect invites, and the current billing position.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ListAccountsOutput" }, "summary": { "type": "string" } }, "required": [ "data", "summary" ] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolError" }, "example": { "error": { "code": "unauthorized", "message": "Invalid or missing API key" } } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolError" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolError" } } } }, "502": { "description": "Provider error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolError" } } } } } } }, "/connect/accounts/{accountId}/posts": { "post": { "operationId": "createPost", "summary": "Publish a post", "description": "Publish a post (text, and optionally an image or a link) to a connected account.", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CreatePostOutput" }, "summary": { "type": "string" } }, "required": [ "data", "summary" ] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolError" }, "example": { "error": { "code": "unauthorized", "message": "Invalid or missing API key" } } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolError" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolError" } } } }, "502": { "description": "Provider error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolError" } } } } }, "requestBody": { "required": true, "description": "Path parameters take precedence; a copy in the body is ignored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePostInput" } } } } } }, "/connect/accounts/{accountId}/reviews": { "get": { "operationId": "listReviews", "summary": "List reviews", "description": "List reviews left on a connected account, newest information first.", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ListReviewsOutput" }, "summary": { "type": "string" } }, "required": [ "data", "summary" ] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolError" }, "example": { "error": { "code": "unauthorized", "message": "Invalid or missing API key" } } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolError" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolError" } } } }, "502": { "description": "Provider error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolError" } } } } } } }, "/connect/accounts/{accountId}/reviews/{reviewId}/reply": { "post": { "operationId": "replyReview", "summary": "Reply to a review", "description": "Post a reply to one review on a connected account.", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "reviewId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ReplyReviewOutput" }, "summary": { "type": "string" } }, "required": [ "data", "summary" ] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolError" }, "example": { "error": { "code": "unauthorized", "message": "Invalid or missing API key" } } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolError" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolError" } } } }, "502": { "description": "Provider error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolError" } } } } }, "requestBody": { "required": true, "description": "Path parameters take precedence; a copy in the body is ignored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplyReviewInput" } } } } } }, "/connect/accounts/{accountId}/insights": { "get": { "operationId": "getInsights", "summary": "Get insights", "description": "Get performance metrics for a connected account over a recent date range.", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "range", "in": "query", "required": false, "schema": { "default": "28d", "type": "string", "enum": [ "7d", "28d", "90d" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/GetInsightsOutput" }, "summary": { "type": "string" } }, "required": [ "data", "summary" ] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolError" }, "example": { "error": { "code": "unauthorized", "message": "Invalid or missing API key" } } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolError" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolError" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolError" } } } }, "502": { "description": "Provider error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolError" } } } } } } } } }