{ "openapi": "3.1.0", "info": { "title": "OwlStack API", "version": "1.0.0", "description": "REST API for OwlStack — schedule, publish, and analyze social media content across every connected platform.\n\n## Authentication\n\nProgrammatic access uses an API key sent in the `X-API-Key` header. Keys are created in the OwlStack dashboard under **Settings → API Keys** and are limited to the scopes granted at creation. Requests from the OwlStack dashboard use a JWT bearer token instead (`Authorization: Bearer `), which implicitly carries all scopes. Either method works on every endpoint in this document unless noted otherwise.\n\n## Scopes\n\nEach operation lists its required scope (also machine-readable as `x-owlstack-scope`): `posts` (includes publishing, deliveries, and media), `workspaces`, `accounts`, `labels`, `webhooks`, `analytics`, `automations`.\n\n## Errors\n\nErrors return `{ \"error\": \"\", \"message\": \"\" }` with a matching HTTP status. Some errors include additional context fields.\n\n## Rate limiting\n\nRequests are rate limited per API key, per minute, with a ceiling set by the plan behind the key. Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`; exceeding the limit returns `429` with error code `too_many_requests`, a `retry_after` field and a `Retry-After` header. Mutating endpoints additionally require an active subscription and return `403` with error code `subscription_required` without one.\n\n## Pagination\n\nList endpoints that paginate accept `page` and `per_page` query parameters and return a `meta` object with `current_page`, `per_page`, `total`, and `last_page`.", "contact": { "name": "FoPost Support", "url": "https://fopost.com/contact" }, "license": { "name": "Proprietary", "url": "https://fopost.com/terms" } }, "servers": [ { "url": "https://api.fopost.com", "description": "Production" } ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "tags": [ { "name": "Posts", "description": "Create and manage posts" }, { "name": "Publishing", "description": "Deliver posts to connected platforms" }, { "name": "Workspaces", "description": "Organize accounts and content" }, { "name": "Accounts", "description": "Connected social accounts" }, { "name": "Communities", "description": "X (Twitter) communities" }, { "name": "Labels", "description": "Tag and organize posts" }, { "name": "Webhooks", "description": "Event notifications for your endpoints" }, { "name": "Analytics", "description": "Performance metrics and audience insights" }, { "name": "Automations", "description": "Trigger-driven publishing workflows" }, { "name": "Media", "description": "Upload and manage media files" }, { "name": "API", "description": "API metadata" } ], "paths": { "/v1/openapi.json": { "get": { "operationId": "getOpenApiSpec", "summary": "Get this OpenAPI document", "tags": [ "API" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "description": "The OpenAPI document" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Returns the OpenAPI 3.1 description of the OwlStack public API. No auth required.", "security": [] } }, "/v1/posts": { "get": { "operationId": "listPosts", "summary": "List posts", "tags": [ "Posts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Lists posts across all workspaces the user belongs to, newest first. All filters are optional and combine with AND semantics.\n\nRequires the `posts` scope when using an API key.", "x-owlstack-scope": "posts", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 30, "minimum": 1, "maximum": 100 } }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to one workspace" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "draft", "scheduled", "publishing", "published", "partially_failed", "failed", "cancelled" ] } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Full-text match against post content" }, { "name": "platform", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated platform names (e.g. `twitter,linkedin`)" }, { "name": "label", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated label uuids" }, { "name": "account_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated account uuids" }, { "name": "date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Only posts created on this day (YYYY-MM-DD, UTC)" }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Range start (inclusive). Scheduled posts filter on schedule time, drafts on creation time." }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Range end (exclusive)" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "oldest" ] }, "description": "Pass `oldest` for ascending order; default is newest first" } ] }, "post": { "operationId": "createPost", "summary": "Create a post", "tags": [ "Posts" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Post" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Creates a draft or scheduled post targeting one or more connected accounts. Content is an ordered list of blocks (threads use multiple blocks).\n\nRequires the `posts` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-owlstack-scope": "posts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePostRequest" } } } } } }, "/v1/posts/{id}": { "get": { "operationId": "getPost", "summary": "Get a post", "tags": [ "Posts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Post" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `posts` scope when using an API key.", "x-owlstack-scope": "posts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Post id" } ] }, "put": { "operationId": "updatePost", "summary": "Update a post", "tags": [ "Posts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Post" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Post is not in a draft or scheduled state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Only draft or scheduled posts can be updated. Arrays (`content`, `accounts`, `labels`, `settings`) are replaced wholesale when provided.\n\nRequires the `posts` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-owlstack-scope": "posts", "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/UpdatePostRequest" } } } } }, "delete": { "operationId": "deletePost", "summary": "Delete a post", "tags": [ "Posts" ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Soft-deletes the post. Already-published platform posts are not removed.\n\nRequires the `posts` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-owlstack-scope": "posts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Post id" } ] } }, "/v1/posts/{id}/publish": { "post": { "operationId": "publishPost", "summary": "Publish a post", "tags": [ "Publishing" ], "responses": { "200": { "description": "Dry run result (only with `options.dryRun`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRunResponse" } } } }, "202": { "description": "Deliveries queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Post is not in a draft or scheduled state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid post id, or all target accounts have expired/revoked credentials (`health_check_failed`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Queues delivery of a draft or scheduled post to its assigned accounts (or the `accountIds` subset). Accounts with expired or revoked credentials are failed immediately; degraded accounts publish with a warning. Delivery is asynchronous — poll the deliveries endpoint or subscribe to webhooks for the outcome. With `options.dryRun` the request validates and returns the target accounts without publishing (200 instead of 202).\n\nRequires the `posts` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-owlstack-scope": "posts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Post id" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishPostRequest" } } } } } }, "/v1/posts/{id}/retry": { "post": { "operationId": "retryPost", "summary": "Retry failed deliveries", "tags": [ "Publishing" ], "responses": { "200": { "description": "Retries queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetryResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Post state does not allow retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid post id, or every selected delivery exceeded the retry limit (`retry_limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Re-queues failed deliveries of a failed, partially failed, or published post. Resending to already-published accounts requires `includePublished: true`. Deliveries past the retry limit are reported in `exceeded` and skipped.\n\nRequires the `posts` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-owlstack-scope": "posts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Post id" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetryPostRequest" } } } } } }, "/v1/posts/{id}/cancel": { "post": { "operationId": "cancelPost", "summary": "Cancel pending deliveries", "tags": [ "Publishing" ], "responses": { "200": { "description": "Deliveries cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Cancels pending, queued, or delayed deliveries (optionally limited to `accountIds`) and recalculates the post status. Send `{}` to cancel all.\n\nRequires the `posts` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-owlstack-scope": "posts", "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/CancelPostRequest" } } } } } }, "/v1/posts/{id}/preflight": { "post": { "operationId": "preflightPost", "summary": "Preflight-check a post", "tags": [ "Publishing" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreflightResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Checks each assigned account for hard blockers (`issues`) and returns advisory per-platform content quality signals. Signals never block publishing.\n\nRequires the `posts` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-owlstack-scope": "posts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Post id" } ] } }, "/v1/posts/{id}/deliveries": { "get": { "operationId": "listDeliveries", "summary": "List deliveries for a post", "tags": [ "Publishing" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Delivery" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Returns the per-account delivery records, newest first.\n\nRequires the `posts` scope when using an API key.", "x-owlstack-scope": "posts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Post id" } ] } }, "/v1/posts/{id}/publish-runs": { "get": { "operationId": "listPostPublishRuns", "summary": "List publish runs for a post", "tags": [ "Publishing" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PublishRun" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "The post’s publish history. Each run is one publish pass over the post and carries the attempts it made per account, with the permalink of anything that went live. Newest run first.\n\nRequires the `posts` scope when using an API key.", "x-owlstack-scope": "posts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Post id" } ] } }, "/v1/posts/{id}/duplicate": { "post": { "operationId": "duplicatePost", "summary": "Duplicate a post", "tags": [ "Posts" ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string" } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Copies the post — content, target accounts, per-platform settings and labels — into a new draft in the same workspace. Schedule, approval and delivery state are not carried over.\n\nRequires the `posts` scope when using an API key.", "x-owlstack-scope": "posts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Post id" } ] } }, "/v1/posts/{id}/analytics": { "get": { "operationId": "getPostAnalytics", "summary": "Get analytics for a post", "tags": [ "Analytics" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostAnalyticsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Aggregated metrics for a post across every platform it was delivered to, using the latest collected snapshot per platform post.\n\nRequires the `posts` scope when using an API key.", "x-owlstack-scope": "posts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Post id" } ] } }, "/v1/posts/bulk": { "post": { "operationId": "bulkUpdatePosts", "summary": "Bulk reschedule, relabel or delete posts", "tags": [ "Posts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "updated": { "type": "integer" }, "action": { "type": "string", "enum": [ "shift", "label", "delete" ] }, "mode": { "type": "string", "enum": [ "replace", "add", "remove" ] } }, "required": [ "updated", "action" ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Applies one action to up to 200 posts in a single transaction. Every post is validated first: any id outside the workspace answers 404 and any post that is no longer draft or scheduled answers 409, in both cases without changing anything. `shift` moves each `schedule_at` by `offset_minutes` (negative moves earlier) and refuses offsets that land in the past; `label` applies `label_ids` with mode `replace` (an empty list clears), `add` or `remove`; `delete` soft-deletes the posts and cancels their queued deliveries.\n\nRequires the `posts` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-owlstack-scope": "posts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "_def": { "typeName": "ZodDiscriminatedUnion", "discriminator": "action", "options": [ { "_def": { "unknownKeys": "strip", "catchall": { "_def": { "typeName": "ZodNever" }, "~standard": { "version": 1, "vendor": "zod" } }, "typeName": "ZodObject" }, "~standard": { "version": 1, "vendor": "zod" }, "_cached": null }, { "_def": { "unknownKeys": "strip", "catchall": { "_def": { "typeName": "ZodNever" }, "~standard": { "version": 1, "vendor": "zod" } }, "typeName": "ZodObject" }, "~standard": { "version": 1, "vendor": "zod" }, "_cached": null }, { "_def": { "unknownKeys": "strip", "catchall": { "_def": { "typeName": "ZodNever" }, "~standard": { "version": 1, "vendor": "zod" } }, "typeName": "ZodObject" }, "~standard": { "version": 1, "vendor": "zod" }, "_cached": null } ], "optionsMap": {} }, "~standard": { "version": 1, "vendor": "zod" } } } } } } }, "/v1/posts/bulk-import/validate": { "post": { "operationId": "validateBulkImport", "summary": "Validate a bulk-import CSV", "tags": [ "Posts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkImportValidation" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Dry-runs a CSV/TSV import (max 500 data rows, 2 MB) and returns per-row validation results without creating anything. Columns: `content` (required), `schedule_at` (ISO 8601 or `YYYY-MM-DD HH:mm` in the workspace timezone), `accounts` (comma-separated account ids or platform names), `labels`, `media_url`, and per-platform overrides `caption_`.\n\nRequires the `posts` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-owlstack-scope": "posts", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "workspace_id": { "type": "string", "format": "uuid" } }, "required": [ "file", "workspace_id" ] } } } } } }, "/v1/posts/bulk-import/commit": { "post": { "operationId": "commitBulkImport", "summary": "Commit a bulk-import CSV", "tags": [ "Posts" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkImportCommitResult" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Re-validates the uploaded CSV/TSV and creates one scheduled post per row, all stamped with a fresh batch id. All-or-nothing: if any row fails validation, nothing is created and the failing rows are returned.\n\nRequires the `posts` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-owlstack-scope": "posts", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "workspace_id": { "type": "string", "format": "uuid" } }, "required": [ "file", "workspace_id" ] } } } } } }, "/v1/posts/bulk-import/{batchId}": { "delete": { "operationId": "rollbackBulkImport", "summary": "Roll back a bulk-import batch", "tags": [ "Posts" ], "responses": { "200": { "description": "Rolled back", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "deleted": { "type": "integer" } }, "required": [ "message", "deleted" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Soft-deletes the batch's posts that are still draft or scheduled and cancels their queued deliveries. Refused with 409 if any post in the batch has already published or is publishing.\n\nRequires the `posts` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-owlstack-scope": "posts", "parameters": [ { "name": "batchId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Import batch id" } ] } }, "/v1/workspaces": { "get": { "operationId": "listWorkspaces", "summary": "List workspaces", "tags": [ "Workspaces" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceWithAccounts" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Lists every workspace the user belongs to, with connected accounts.\n\nRequires the `workspaces` scope when using an API key.", "x-owlstack-scope": "workspaces" }, "post": { "operationId": "createWorkspace", "summary": "Create a workspace", "tags": [ "Workspaces" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Workspace" } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "Workspace limit reached for the current plan (`workspace_limit`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "Slug already in use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `workspaces` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-owlstack-scope": "workspaces", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWorkspaceRequest" } } } } } }, "/v1/workspaces/{id}": { "get": { "operationId": "getWorkspace", "summary": "Get a workspace", "tags": [ "Workspaces" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WorkspaceWithAccounts" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `workspaces` scope when using an API key.", "x-owlstack-scope": "workspaces", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Workspace id" } ] }, "put": { "operationId": "updateWorkspace", "summary": "Update a workspace", "tags": [ "Workspaces" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Workspace" } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Slug already in use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the workspace owner or admin role.\n\nRequires the `workspaces` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-owlstack-scope": "workspaces", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Workspace id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWorkspaceRequest" } } } } }, "delete": { "operationId": "deleteWorkspace", "summary": "Delete a workspace", "tags": [ "Workspaces" ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Soft-deletes the workspace. Requires the workspace owner role.\n\nRequires the `workspaces` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-owlstack-scope": "workspaces", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Workspace id" } ] } }, "/v1/workspaces/{id}/analytics": { "get": { "operationId": "getWorkspaceAnalytics", "summary": "Get workspace analytics", "tags": [ "Analytics" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAnalyticsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Latest follower and post totals for every account in the workspace.\n\nRequires the `workspaces` scope when using an API key.", "x-owlstack-scope": "workspaces", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Workspace id" } ] } }, "/v1/accounts": { "get": { "operationId": "listAccounts", "summary": "List connected accounts", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AccountSummary" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `accounts` scope when using an API key.", "x-owlstack-scope": "accounts", "parameters": [ { "name": "workspaceId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" } ] }, "post": { "operationId": "createAccount", "summary": "Connect an account with credentials", "tags": [ "Accounts" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AccountCreated" } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Creates a connected account from caller-supplied credentials (for platforms that use tokens or keys instead of an OAuth redirect flow). Credentials are validated against the platform before the account is stored.\n\nRequires the `accounts` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-owlstack-scope": "accounts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccountRequest" } } } } } }, "/v1/accounts/health": { "get": { "operationId": "getAccountsHealthSummary", "summary": "Get health summary for all accounts", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountsHealthSummaryResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `accounts` scope when using an API key.", "x-owlstack-scope": "accounts", "parameters": [ { "name": "workspaceId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" } ] } }, "/v1/accounts/{id}": { "get": { "operationId": "getAccount", "summary": "Get an account", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AccountDetail" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `accounts` scope when using an API key.", "x-owlstack-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Account id" } ] }, "delete": { "operationId": "deleteAccount", "summary": "Disconnect an account", "tags": [ "Accounts" ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Revokes platform access where supported, clears stored credentials, and soft-deletes the account.\n\nRequires the `accounts` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-owlstack-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Account id" } ] } }, "/v1/accounts/{id}/primary": { "post": { "operationId": "toggleAccountPrimary", "summary": "Toggle primary flag", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "isPrimary": { "type": "boolean" } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `accounts` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-owlstack-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Account id" } ] } }, "/v1/accounts/{id}/validate": { "post": { "operationId": "validateAccountCredentials", "summary": "Validate account credentials", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "accountId": { "type": "string", "format": "uuid" }, "platform": { "type": "string" }, "valid": { "type": "boolean" }, "healthStatus": { "type": "string", "enum": [ "healthy", "expired" ] } } } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Checks the stored credentials against the platform and updates the health status.\n\nRequires the `accounts` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-owlstack-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Account id" } ] } }, "/v1/accounts/{id}/health": { "get": { "operationId": "getAccountHealth", "summary": "Get account health", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AccountHealth" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `accounts` scope when using an API key.", "x-owlstack-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Account id" }, { "name": "refresh", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "Pass `true` to run a fresh health check" } ] } }, "/v1/accounts/{id}/refresh-token": { "post": { "operationId": "refreshAccountToken", "summary": "Refresh an OAuth token", "tags": [ "Accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "message": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" } } } }, "required": [ "data" ] } } } }, "400": { "description": "Platform does not support token refresh, or the refresh failed (`token_refresh_failed`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Manually refreshes the OAuth token for platforms that support it.\n\nRequires the `accounts` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-owlstack-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Account id" } ] } }, "/v1/accounts/{id}/analytics": { "get": { "operationId": "getAccountAnalyticsHistory", "summary": "Get account analytics history", "tags": [ "Analytics" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountAnalyticsHistoryResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Account-level snapshots (followers, reach, profile views), newest first.\n\nRequires the `accounts` scope when using an API key.", "x-owlstack-scope": "accounts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Account id" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 30, "maximum": 100 } } ] } }, "/v1/accounts/{accountId}/communities": { "get": { "operationId": "listCommunities", "summary": "List X communities for an account", "tags": [ "Communities" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Community" } } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Only X (Twitter) accounts have communities.\n\nRequires the `accounts` scope when using an API key.", "x-owlstack-scope": "accounts", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Account id (must be an X account)" } ] } }, "/v1/accounts/{accountId}/communities/sync": { "post": { "operationId": "syncCommunities", "summary": "Sync communities from X", "tags": [ "Communities" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Community" } }, "note": { "type": "string" } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Fetches the account’s communities from X. Falls back to the stored list (with an explanatory `note`) when the X API is unavailable.\n\nRequires the `accounts` scope when using an API key.", "x-owlstack-scope": "accounts", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Account id (must be an X account)" } ] } }, "/v1/accounts/{accountId}/communities/search": { "get": { "operationId": "searchCommunities", "summary": "Search X communities", "tags": [ "Communities" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "member_count": { "type": "integer" } } } } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "The X API rejected the search", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Requires the `accounts` scope when using an API key.", "x-owlstack-scope": "accounts", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Account id (must be an X account)" }, { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Search keyword" } ] } }, "/v1/accounts/{accountId}/communities/manual": { "post": { "operationId": "addCommunityManually", "summary": "Add a community by id", "tags": [ "Communities" ], "responses": { "200": { "description": "Community was already linked", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Community" } }, "required": [ "data" ] } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Community" } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Returns the existing record (200) if the community is already linked.\n\nRequires the `accounts` scope when using an API key.", "x-owlstack-scope": "accounts", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Account id (must be an X account)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddCommunityRequest" } } } } } }, "/v1/accounts/{accountId}/communities/{communityId}": { "delete": { "operationId": "removeCommunity", "summary": "Remove a community", "tags": [ "Communities" ], "responses": { "200": { "description": "Removed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `accounts` scope when using an API key.", "x-owlstack-scope": "accounts", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Account id" }, { "name": "communityId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Internal community id (from the list response)" } ] } }, "/v1/labels": { "get": { "operationId": "listLabels", "summary": "List labels", "tags": [ "Labels" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LabelListItem" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `labels` scope when using an API key.", "x-owlstack-scope": "labels", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" } ] }, "post": { "operationId": "createLabel", "summary": "Create a label", "tags": [ "Labels" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Label" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `labels` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-owlstack-scope": "labels", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLabelRequest" } } } } } }, "/v1/labels/{id}": { "get": { "operationId": "getLabel", "summary": "Get a label", "tags": [ "Labels" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Label" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `labels` scope when using an API key.", "x-owlstack-scope": "labels", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Label id" } ] }, "put": { "operationId": "updateLabel", "summary": "Update a label", "tags": [ "Labels" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Label" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `labels` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-owlstack-scope": "labels", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Label id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLabelRequest" } } } } }, "delete": { "operationId": "deleteLabel", "summary": "Delete a label", "tags": [ "Labels" ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `labels` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-owlstack-scope": "labels", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Label id" } ] } }, "/v1/webhooks": { "get": { "operationId": "listWebhooks", "summary": "List webhooks", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `webhooks` scope when using an API key.", "x-owlstack-scope": "webhooks" }, "post": { "operationId": "createWebhook", "summary": "Create a webhook", "tags": [ "Webhooks" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookCreated" } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Registers an HTTPS endpoint for workspace events. The signing `secret` is returned only in this response — store it to verify payloads.\n\nRequires the `webhooks` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-owlstack-scope": "webhooks", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookRequest" } } } } } }, "/v1/webhooks/{id}": { "put": { "operationId": "updateWebhook", "summary": "Update a webhook", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookUpdated" } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Re-enabling a webhook (`active: true`) resets its failure count.\n\nRequires the `webhooks` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-owlstack-scope": "webhooks", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Webhook id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookRequest" } } } } }, "delete": { "operationId": "deleteWebhook", "summary": "Delete a webhook", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `webhooks` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-owlstack-scope": "webhooks", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Webhook id" } ] } }, "/v1/webhooks/{id}/test": { "post": { "operationId": "testWebhook", "summary": "Send a test event", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Test dispatched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Dispatches a test `post.published` payload to the webhook endpoint.\n\nRequires the `webhooks` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-owlstack-scope": "webhooks", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Webhook id" } ] } }, "/v1/analytics/overview": { "get": { "operationId": "getAnalyticsOverview", "summary": "Get analytics overview", "tags": [ "Analytics" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsOverviewResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Cross-workspace dashboard totals, period deltas, today’s stats, and a per-account breakdown with follower history.\n\nRequires the `analytics` scope when using an API key.", "x-owlstack-scope": "analytics", "parameters": [ { "name": "accountId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single connected account" }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "default": 7, "minimum": 1, "maximum": 365 }, "description": "Length of the reporting period in days" } ] } }, "/v1/analytics/time-series": { "get": { "operationId": "getAnalyticsTimeSeries", "summary": "Get daily time series", "tags": [ "Analytics" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimeSeriesResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Daily-bucketed engagement, follower, and post counts. Use either `days` or an explicit `from`/`to` range.\n\nRequires the `analytics` scope when using an API key.", "x-owlstack-scope": "analytics", "parameters": [ { "name": "accountId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single connected account" }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "default": 7, "minimum": 1, "maximum": 365 } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Range start (used together with `to`)" }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Range end (used together with `from`)" } ] } }, "/v1/analytics/top-posts": { "get": { "operationId": "getTopPerformingPosts", "summary": "Get top performing posts", "tags": [ "Analytics" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TopPost" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Posts ranked by engagement (or newest first with `sort=recent`). Includes platform-native posts not published through OwlStack.\n\nRequires the `analytics` scope when using an API key.", "x-owlstack-scope": "analytics", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 5, "minimum": 1, "maximum": 50 } }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "default": 7, "minimum": 1, "maximum": 365 } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Range start (used together with `to`)" }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Range end (used together with `from`)" }, { "name": "accountId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single connected account" }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "recent" ] }, "description": "Pass `recent` to sort newest first instead of by engagement" }, { "name": "label", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Keep only posts carrying this label. Applied before `limit`, so it narrows the whole period rather than the page." } ] } }, "/v1/analytics/labels": { "get": { "operationId": "getLabelAnalytics", "summary": "Get per-label campaign roll-up", "tags": [ "Analytics" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LabelAnalytics" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Post metrics rolled up per label, ranked by engagement. Only posts published through OwlStack carry labels, so platform-native and unlabelled posts are excluded. A post on two labels counts in full toward each.\n\nRequires the `analytics` scope when using an API key.", "x-owlstack-scope": "analytics", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "default": 7, "minimum": 1, "maximum": 365 } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Range start (used together with `to`)" }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Range end (used together with `from`)" }, { "name": "accountId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single connected account" }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" } ] } }, "/v1/analytics/posts-table": { "get": { "operationId": "getPostsTable", "summary": "Get posts with delivery breakdown", "tags": [ "Analytics" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostsTableResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Paginated posts of every status with per-delivery outcomes and a status summary.\n\nRequires the `analytics` scope when using an API key.", "x-owlstack-scope": "analytics", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, { "name": "accountId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single connected account" }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 90 } } ] } }, "/v1/analytics/posting-streak": { "get": { "operationId": "getPostingStreak", "summary": "Get 365-day posting activity", "tags": [ "Analytics" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostingStreakResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `analytics` scope when using an API key.", "x-owlstack-scope": "analytics", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" } ] } }, "/v1/analytics/demographics": { "get": { "operationId": "getAudienceDemographics", "summary": "Get audience demographics", "tags": [ "Analytics" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DemographicsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Latest age, gender, country, and city splits summed across the selected accounts, with the list of accounts that did or did not contribute data.\n\nRequires the `analytics` scope when using an API key.", "x-owlstack-scope": "analytics", "parameters": [ { "name": "audience", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "followers", "engaged", "reached" ], "default": "followers" } }, { "name": "accountId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single connected account" }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single workspace the user belongs to" } ] } }, "/v1/analytics/collect": { "post": { "operationId": "triggerAnalyticsCollect", "summary": "Trigger analytics collection", "tags": [ "Analytics" ], "responses": { "200": { "description": "Collection summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectSummaryResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "description": "Collection throttled — retry after `retryAfter` seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Collects fresh metrics for the user’s active accounts on demand. Throttled per user; when throttled the 429 body includes `retryAfter` (seconds).\n\nRequires the `analytics` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-owlstack-scope": "analytics", "parameters": [ { "name": "accountId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Restrict to a single connected account" } ] } }, "/v1/automations": { "get": { "operationId": "listAutomations", "summary": "List automations", "tags": [ "Automations" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Automation" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `automations` scope when using an API key.", "x-owlstack-scope": "automations" }, "post": { "operationId": "createAutomation", "summary": "Create an automation", "tags": [ "Automations" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AutomationCreated" } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Creates a trigger → pipeline workflow. The webhook trigger `secret` is returned only in this response.\n\nRequires the `automations` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-owlstack-scope": "automations", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAutomationRequest" } } } } } }, "/v1/automations/stats": { "get": { "operationId": "getAutomationStats", "summary": "Get automation stats", "tags": [ "Automations" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationStatsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Totals plus run counts by status for the last 24 hours and the 10 latest runs.\n\nRequires the `automations` scope when using an API key.", "x-owlstack-scope": "automations" } }, "/v1/automations/{id}": { "get": { "operationId": "getAutomation", "summary": "Get an automation", "tags": [ "Automations" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AutomationDetail" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `automations` scope when using an API key.", "x-owlstack-scope": "automations", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Automation id" } ] }, "put": { "operationId": "updateAutomation", "summary": "Update an automation", "tags": [ "Automations" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AutomationDetail" } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "When `steps` is provided the full step list is replaced.\n\nRequires the `automations` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-owlstack-scope": "automations", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Automation id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAutomationRequest" } } } } }, "delete": { "operationId": "deleteAutomation", "summary": "Delete an automation", "tags": [ "Automations" ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "deleted": { "type": "boolean" } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `automations` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-owlstack-scope": "automations", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Automation id" } ] } }, "/v1/automations/{id}/toggle": { "post": { "operationId": "toggleAutomation", "summary": "Toggle an automation on or off", "tags": [ "Automations" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "active": { "type": "boolean" } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `automations` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-owlstack-scope": "automations", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Automation id" } ] } }, "/v1/automations/{id}/runs": { "get": { "operationId": "listAutomationRuns", "summary": "List automation runs", "tags": [ "Automations" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AutomationRun" } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "last_page": { "type": "integer" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `automations` scope when using an API key.", "x-owlstack-scope": "automations", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Automation id" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 30, "minimum": 1, "maximum": 100 } } ] } }, "/v1/automations/{id}/runs/{runId}": { "get": { "operationId": "getAutomationRun", "summary": "Get an automation run", "tags": [ "Automations" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AutomationRunDetail" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Includes per-step execution logs.\n\nRequires the `automations` scope when using an API key.", "x-owlstack-scope": "automations", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Automation id" }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Run id" } ] } }, "/v1/automations/{id}/trigger": { "post": { "operationId": "triggerAutomationWebhook", "summary": "Trigger an automation via webhook", "tags": [ "Automations" ], "responses": { "200": { "description": "Run started", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "runId": { "type": "integer" }, "triggered": { "type": "boolean" } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/InvalidId" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Public endpoint for `api_webhook` automations. Authenticated by the automation’s secret in the `x-automation-secret` header (returned when the automation was created), not by an API key. The JSON body (optional) becomes the trigger payload.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Automation id" } ], "requestBody": { "required": false, "description": "Arbitrary trigger payload", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "security": [] } }, "/v1/media": { "get": { "operationId": "listMedia", "summary": "List media library items", "tags": [ "Media" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MediaLibraryItem" } } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requires the `posts` scope when using an API key.", "x-owlstack-scope": "posts", "parameters": [ { "name": "workspaceId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Workspace to list media for" } ] } }, "/v1/media/upload": { "post": { "operationId": "uploadMedia", "summary": "Upload media files", "tags": [ "Media" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UploadedMedia" } } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Accepts up to 5 files (max 50 MB each) as multipart/form-data under the `files` field. Allowed types: jpeg, png, gif, webp, mp4, mov, webm, pdf, txt, csv. File content is verified against the declared type. When `workspaceId` is provided the files are also saved to the media library.\n\nRequires the `posts` scope when using an API key.\n\nRequires an active subscription; without one the request fails with 403 `subscription_required`.", "x-owlstack-scope": "posts", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "string", "format": "binary" } }, "workspaceId": { "type": "string", "format": "uuid" } }, "required": [ "files" ] } } } } } }, "/v1/media/{id}": { "delete": { "operationId": "deleteMedia", "summary": "Delete a media item", "tags": [ "Media" ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Removes the stored file and the media library record.\n\nRequires the `posts` scope when using an API key.", "x-owlstack-scope": "posts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Media library id" } ] } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "API key created in the OwlStack dashboard. A key may be bound to a single workspace, in which case every request is confined to it: naming any other workspace returns 403, and listings return only that workspace. Keys created without a workspace keep access to every workspace on the account." }, "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Session token used by the OwlStack dashboard" } }, "schemas": { "CreatePostRequest": { "type": "object", "properties": { "workspace_id": { "type": "string", "format": "uuid" }, "accounts": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "content": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": [ "string", "null" ] }, "media": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image", "video", "gif" ] }, "name": { "type": "string", "minLength": 1 }, "url": { "type": "string", "format": "uri" }, "size": { "type": "number", "exclusiveMinimum": 0 }, "alt": { "type": "string" }, "thumbnail": { "type": "string", "format": "uri" } }, "required": [ "type", "name", "url" ] } } } }, "minItems": 1 }, "content_type": { "type": "string", "enum": [ "post", "thread", "reel" ], "default": "post" }, "artifact_type": { "type": "string", "enum": [ "text_post", "thread", "article", "carousel", "short_video", "link_share" ], "default": "text_post" }, "status": { "type": "string", "enum": [ "draft", "scheduled" ], "default": "draft" }, "schedule_at": { "type": [ "string", "null" ], "format": "date-time" }, "repeatable": { "type": "boolean", "default": false }, "repeatable_times": { "type": [ "integer", "null" ], "exclusiveMinimum": 0 }, "repeatable_gap": { "type": [ "integer", "null" ], "exclusiveMinimum": 0 }, "repeatable_gap_unit": { "type": [ "string", "null" ], "enum": [ "hours", "days", "weeks", "months" ] }, "labels": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "title": { "type": [ "string", "null" ], "maxLength": 255 }, "internal_title": { "type": [ "string", "null" ], "maxLength": 255 }, "summary": { "type": [ "string", "null" ], "maxLength": 500 }, "auto_plug": { "type": "boolean", "default": false }, "auto_plug_content": { "type": [ "string", "null" ], "maxLength": 500 }, "settings": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": {} } }, "source_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 5 }, "companion_of": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "workspace_id", "accounts", "content" ] }, "UpdatePostRequest": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1 }, "content": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": [ "string", "null" ] }, "media": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image", "video", "gif" ] }, "name": { "type": "string", "minLength": 1 }, "url": { "type": "string", "format": "uri" }, "size": { "type": "number", "exclusiveMinimum": 0 }, "alt": { "type": "string" }, "thumbnail": { "type": "string", "format": "uri" } }, "required": [ "type", "name", "url" ] } } } }, "minItems": 1 }, "content_type": { "type": "string", "enum": [ "post", "thread", "reel" ] }, "artifact_type": { "type": "string", "enum": [ "text_post", "thread", "article", "carousel", "short_video", "link_share" ] }, "status": { "type": "string", "enum": [ "draft", "scheduled" ] }, "schedule_at": { "type": [ "string", "null" ], "format": "date-time" }, "repeatable": { "type": "boolean" }, "repeatable_times": { "type": [ "integer", "null" ], "exclusiveMinimum": 0 }, "repeatable_gap": { "type": [ "integer", "null" ], "exclusiveMinimum": 0 }, "repeatable_gap_unit": { "type": [ "string", "null" ], "enum": [ "hours", "days", "weeks", "months" ] }, "labels": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "title": { "type": [ "string", "null" ], "maxLength": 255 }, "internal_title": { "type": [ "string", "null" ], "maxLength": 255 }, "summary": { "type": [ "string", "null" ], "maxLength": 500 }, "auto_plug": { "type": "boolean" }, "auto_plug_content": { "type": [ "string", "null" ], "maxLength": 500 }, "settings": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": {} } } } }, "PublishPostRequest": { "type": "object", "properties": { "accountIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1 }, "options": { "type": "object", "properties": { "dryRun": { "type": "boolean" } } } } }, "RetryPostRequest": { "type": "object", "properties": { "accountIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "includePublished": { "type": "boolean" } } }, "CancelPostRequest": { "type": "object", "properties": { "accountIds": { "type": "array", "items": { "type": "string", "format": "uuid" } } } }, "CreateAccountRequest": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "twitter", "instagram", "instagram-business", "facebook", "linkedin", "tiktok", "youtube", "bluesky", "threads", "mastodon", "lemmy", "pinterest", "telegram", "twitch", "discord", "slack", "reddit", "tumblr", "dribbble", "mewe", "devto", "hashnode", "medium", "substack", "google-business", "kick", "listmonk", "wordpress", "nostr", "whop", "skool" ] }, "username": { "type": "string", "minLength": 1, "maxLength": 255 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "avatar": { "type": [ "string", "null" ], "maxLength": 500 }, "credentials": { "type": "object", "additionalProperties": {} } }, "required": [ "workspaceId", "platform", "username", "name" ] }, "CreateWorkspaceRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "slug": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[a-z0-9-]+$" }, "type": { "type": "string", "enum": [ "PERSONAL", "TEAM", "ORGANIZATION", "CLIENT", "PROJECT", "DEPARTMENT", "EVENT", "TEMPORARY", "COMMUNITY", "BRAND", "AGENCY" ], "default": "PERSONAL" }, "logo": { "type": [ "string", "null" ], "maxLength": 500 }, "website": { "type": [ "string", "null" ], "maxLength": 500 }, "timezone": { "type": "string", "maxLength": 100, "default": "UTC" }, "country": { "type": [ "string", "null" ], "maxLength": 100 }, "description": { "type": [ "string", "null" ], "maxLength": 2000 }, "language": { "type": "string", "maxLength": 10, "default": "en" } }, "required": [ "name", "slug" ] }, "UpdateWorkspaceRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "slug": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[a-z0-9-]+$" }, "type": { "type": "string", "enum": [ "PERSONAL", "TEAM", "ORGANIZATION", "CLIENT", "PROJECT", "DEPARTMENT", "EVENT", "TEMPORARY", "COMMUNITY", "BRAND", "AGENCY" ] }, "logo": { "type": [ "string", "null" ], "maxLength": 500 }, "website": { "type": [ "string", "null" ], "maxLength": 500 }, "timezone": { "type": "string", "maxLength": 100 }, "country": { "type": [ "string", "null" ], "maxLength": 100 }, "description": { "type": [ "string", "null" ], "maxLength": 2000 }, "language": { "type": "string", "maxLength": 10 }, "requireApproval": { "type": "boolean" }, "aiAltTextEnabled": { "type": "boolean" }, "brandColor": { "type": [ "string", "null" ], "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$" } } }, "CreateLabelRequest": { "type": "object", "properties": { "workspace_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" } }, "required": [ "workspace_id", "name", "color" ] }, "UpdateLabelRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" } }, "required": [ "name", "color" ] }, "CreateWebhookRequest": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "post.published", "post.failed", "post.partially_failed", "delivery.published", "delivery.failed", "delivery.delayed", "account.health_changed" ] }, "minItems": 1 } }, "required": [ "workspaceId", "url", "events" ] }, "UpdateWebhookRequest": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "post.published", "post.failed", "post.partially_failed", "delivery.published", "delivery.failed", "delivery.delayed", "account.health_changed" ] }, "minItems": 1 }, "active": { "type": "boolean" } } }, "CreateAutomationRequest": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "triggerType": { "type": "string", "enum": [ "cross_post", "rss_feed", "api_webhook", "schedule" ] }, "triggerConfig": { "type": "object", "additionalProperties": {}, "default": {} }, "steps": { "type": "array", "items": { "type": "object", "properties": { "actionType": { "type": "string", "enum": [ "publish", "delay", "transform" ] }, "actionConfig": { "type": "object", "additionalProperties": {}, "default": {} } }, "required": [ "actionType" ] }, "minItems": 1, "maxItems": 20 }, "active": { "type": "boolean", "default": true } }, "required": [ "workspaceId", "name", "triggerType", "steps" ] }, "UpdateAutomationRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "triggerConfig": { "type": "object", "additionalProperties": {} }, "steps": { "type": "array", "items": { "type": "object", "properties": { "actionType": { "type": "string", "enum": [ "publish", "delay", "transform" ] }, "actionConfig": { "type": "object", "additionalProperties": {}, "default": {} } }, "required": [ "actionType" ] }, "minItems": 1, "maxItems": 20 }, "active": { "type": "boolean" } } }, "AddCommunityRequest": { "type": "object", "properties": { "communityId": { "type": "string" }, "name": { "type": "string" } }, "required": [ "communityId" ] }, "Error": { "type": "object", "properties": { "error": { "type": "string", "description": "Machine-readable error code" }, "message": { "type": "string", "description": "Human-readable explanation" } }, "required": [ "error" ], "additionalProperties": true, "description": "Standard error envelope. Some errors carry additional context fields (for example `exceeded`, `healthWarnings`, `retryAfter`)." }, "Message": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "PageMeta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "last_page": { "type": "integer" }, "from": { "type": "integer", "description": "1-based index of the first item on this page (0 when empty)" }, "to": { "type": "integer", "description": "1-based index of the last item on this page" } }, "required": [ "current_page", "per_page", "total", "last_page", "from", "to" ] }, "MediaItem": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image", "video", "gif" ] }, "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "size": { "type": "number", "description": "File size in bytes" }, "alt": { "type": "string" }, "thumbnail": { "type": "string", "format": "uri" } }, "required": [ "type", "name", "url" ] }, "PostContentBlock": { "type": "object", "properties": { "id": { "type": "integer" }, "text": { "type": [ "string", "null" ] }, "media": { "type": "array", "items": { "$ref": "#/components/schemas/MediaItem" } }, "position": { "type": "integer" } } }, "PostAccountResult": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Social account id" }, "platform": { "type": "string" }, "username": { "type": "string" }, "name": { "type": "string" }, "avatar": { "type": [ "string", "null" ] }, "publish_status": { "type": "string", "enum": [ "pending", "queued", "delayed", "publishing", "published", "failed", "cancelled" ] }, "posted_at": { "type": [ "string", "null" ], "format": "date-time" }, "platform_post_id": { "type": [ "string", "null" ] }, "external_url": { "type": [ "string", "null" ] }, "error_code": { "type": [ "string", "null" ] }, "error_message": { "type": [ "string", "null" ], "description": "User-friendly error message" }, "raw_error_message": { "type": [ "string", "null" ], "description": "Raw error message from the platform" }, "attempts": { "type": "integer" }, "max_attempts": { "type": "integer" } } }, "PostLabelRef": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "type": "string" } } }, "Post": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "publishing", "published", "partially_failed", "failed", "cancelled" ] }, "content_type": { "type": "string", "enum": [ "post", "thread", "reel" ] }, "schedule_at": { "type": [ "string", "null" ], "format": "date-time" }, "repeatable": { "type": "boolean" }, "repeatable_times": { "type": [ "integer", "null" ] }, "repeatable_gap": { "type": [ "integer", "null" ] }, "repeatable_gap_unit": { "type": [ "string", "null" ], "enum": [ "hours", "days", "weeks", "months", null ] }, "remaining_posts": { "type": [ "integer", "null" ] }, "title": { "type": [ "string", "null" ] }, "summary": { "type": [ "string", "null" ] }, "auto_plug": { "type": "boolean" }, "auto_plug_content": { "type": [ "string", "null" ] }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/PostContentBlock" } }, "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/PostAccountResult" } }, "labels": { "type": "array", "items": { "$ref": "#/components/schemas/PostLabelRef" } }, "settings": { "type": "object", "description": "Per-account platform settings, keyed by account id", "additionalProperties": { "type": "object" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "workspace_id", "status", "content_type", "content", "accounts", "labels" ] }, "PostListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } }, "required": [ "data", "meta" ] }, "HealthWarning": { "type": "object", "properties": { "accountId": { "type": "string", "format": "uuid" }, "platform": { "type": "string" }, "healthStatus": { "type": "string" }, "message": { "type": "string" } } }, "PublishDelivery": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Delivery id" }, "accountId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "queued", "delayed", "publishing", "published", "failed", "cancelled" ] }, "errorCode": { "type": [ "string", "null" ] }, "errorMessage": { "type": [ "string", "null" ] }, "platformPostId": { "type": [ "string", "null" ] }, "externalUrl": { "type": [ "string", "null" ] }, "postedAt": { "type": [ "string", "null" ], "format": "date-time" }, "attempts": { "type": "integer" }, "scheduledPublishAt": { "type": [ "string", "null" ], "format": "date-time" }, "delayReason": { "type": [ "string", "null" ] }, "delayMessage": { "type": [ "string", "null" ] } } }, "PublishResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "post_status": { "type": "string", "enum": [ "draft", "scheduled", "publishing", "published", "partially_failed", "failed", "cancelled" ] }, "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/PublishDelivery" } }, "healthWarnings": { "type": "array", "items": { "$ref": "#/components/schemas/HealthWarning" } } } } }, "required": [ "data" ] }, "DryRunResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "dryRun": { "type": "boolean", "const": true }, "post": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "publishing", "published", "partially_failed", "failed", "cancelled" ] } } }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "accountId": { "type": "string", "format": "uuid" }, "platform": { "type": "string" } } } }, "healthWarnings": { "type": "array", "items": { "$ref": "#/components/schemas/HealthWarning" } } } } }, "required": [ "data" ] }, "RetryResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "post_status": { "type": "string", "enum": [ "draft", "scheduled", "publishing", "published", "partially_failed", "failed", "cancelled" ] }, "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/PublishDelivery" } }, "exceeded": { "type": "array", "items": { "type": "object", "properties": { "accountId": { "type": "string", "format": "uuid" }, "platform": { "type": "string" }, "attempts": { "type": "integer" } } }, "description": "Deliveries skipped because they exceeded the retry limit" } } } }, "required": [ "data" ] }, "CancelResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "post_status": { "type": "string", "enum": [ "draft", "scheduled", "publishing", "published", "partially_failed", "failed", "cancelled" ] }, "deliveries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "accountId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "queued", "delayed", "publishing", "published", "failed", "cancelled" ] } } } } } } }, "required": [ "data" ] }, "ContentSignal": { "type": "object", "properties": { "level": { "type": "string", "enum": [ "info", "warn" ] }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "level", "code", "message" ] }, "PreflightResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ready": { "type": "boolean" }, "post": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "publishing", "published", "partially_failed", "failed", "cancelled" ] } } }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "accountId": { "type": "string", "format": "uuid" }, "platform": { "type": "string" }, "username": { "type": "string" }, "ready": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "string" }, "description": "Hard blockers that prevent publishing" }, "score": { "type": "number", "description": "Advisory 0-100 content quality score for this platform" }, "signals": { "type": "array", "items": { "$ref": "#/components/schemas/ContentSignal" }, "description": "Advisory signals — they never block publishing" } } } } } } }, "required": [ "data" ] }, "Delivery": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "accountId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "queued", "delayed", "publishing", "published", "failed", "cancelled" ] }, "errorCode": { "type": [ "string", "null" ] }, "errorMessage": { "type": [ "string", "null" ] }, "attempts": { "type": "integer" }, "maxAttempts": { "type": "integer" }, "scheduledPublishAt": { "type": [ "string", "null" ], "format": "date-time" }, "delayReason": { "type": [ "string", "null" ] }, "delayMessage": { "type": [ "string", "null" ] }, "postedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastAttemptAt": { "type": [ "string", "null" ], "format": "date-time" }, "platformPostId": { "type": [ "string", "null" ] }, "externalUrl": { "type": [ "string", "null" ] }, "platform": { "type": "string" }, "username": { "type": "string" }, "accountName": { "type": "string" } } }, "PublishRunDelivery": { "type": "object", "properties": { "account_id": { "type": "string", "format": "uuid" }, "account_name": { "type": "string" }, "username": { "type": "string" }, "platform": { "type": "string" }, "status": { "type": "string" }, "attempt_number": { "type": "integer" }, "error_code": { "type": [ "string", "null" ] }, "error_message": { "type": [ "string", "null" ] }, "platform_post_id": { "type": [ "string", "null" ] }, "external_url": { "type": [ "string", "null" ] }, "started_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "duration_ms": { "type": [ "integer", "null" ] } } }, "PublishRun": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "run_number": { "type": "integer" }, "status": { "type": "string", "enum": [ "running", "published", "partially_failed", "failed", "cancelled" ] }, "started_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/PublishRunDelivery" } } } }, "BulkImportRowResult": { "type": "object", "properties": { "row": { "type": "integer" }, "content_preview": { "type": "string" }, "schedule_at": { "type": [ "string", "null" ], "format": "date-time" }, "accounts": { "type": "array", "items": { "type": "string" } }, "labels": { "type": "integer" }, "has_media": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "string" } } } }, "BulkImportValidation": { "type": "object", "properties": { "total_rows": { "type": "integer" }, "valid_rows": { "type": "integer" }, "invalid_rows": { "type": "integer" }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/BulkImportRowResult" } } }, "required": [ "total_rows", "valid_rows", "invalid_rows", "rows" ] }, "BulkImportCommitResult": { "type": "object", "properties": { "batch_id": { "type": "string", "format": "uuid" }, "created": { "type": "integer" }, "posts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "schedule_at": { "type": [ "string", "null" ], "format": "date-time" } } } } }, "required": [ "batch_id", "created", "posts" ] }, "PostAnalyticsMetrics": { "type": "object", "properties": { "impressions": { "type": [ "integer", "null" ] }, "reach": { "type": [ "integer", "null" ] }, "engagements": { "type": [ "integer", "null" ] }, "likes": { "type": [ "integer", "null" ] }, "comments": { "type": [ "integer", "null" ] }, "shares": { "type": [ "integer", "null" ] }, "reposts": { "type": [ "integer", "null" ] }, "clicks": { "type": [ "integer", "null" ] }, "saves": { "type": [ "integer", "null" ] }, "videoViews": { "type": [ "integer", "null" ] }, "watchTimeMs": { "type": [ "integer", "null" ] }, "avgWatchTimeMs": { "type": [ "integer", "null" ] }, "reactionsBreakdown": { "type": [ "object", "null" ], "additionalProperties": { "type": "integer" } }, "follows": { "type": [ "integer", "null" ] }, "fetchedAt": { "type": "string", "format": "date-time" } } }, "PostAnalyticsResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "postId": { "type": "string", "format": "uuid" }, "totals": { "type": "object", "properties": { "impressions": { "type": "integer" }, "reach": { "type": "integer" }, "engagements": { "type": "integer" }, "likes": { "type": "integer" }, "comments": { "type": "integer" }, "shares": { "type": "integer" }, "reposts": { "type": "integer" }, "clicks": { "type": "integer" }, "saves": { "type": "integer" }, "videoViews": { "type": "integer" }, "follows": { "type": "integer" } } }, "platforms": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "username": { "type": "string" }, "externalPostId": { "type": [ "string", "null" ] }, "permalink": { "type": [ "string", "null" ] }, "thumbnailUrl": { "type": [ "string", "null" ] }, "mediaType": { "type": [ "string", "null" ] }, "postedAt": { "type": [ "string", "null" ], "format": "date-time" }, "metrics": { "oneOf": [ { "$ref": "#/components/schemas/PostAnalyticsMetrics" }, { "type": "null" } ] } } } }, "lastFetchedAt": { "type": [ "string", "null" ], "format": "date-time" } } } }, "required": [ "data" ] }, "WorkspaceAccountRef": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspaceId": { "type": "string", "format": "uuid" }, "platform": { "type": "string" }, "username": { "type": "string" }, "name": { "type": "string" }, "avatar": { "type": [ "string", "null" ] } } }, "Workspace": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "type": { "type": "string" }, "logo": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "timezone": { "type": "string" }, "country": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "language": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "slug", "type", "timezone", "language", "created_at" ] }, "WorkspaceWithAccounts": { "allOf": [ { "$ref": "#/components/schemas/Workspace" }, { "type": "object", "properties": { "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceAccountRef" } } } } ] }, "WorkspaceAnalyticsResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid" }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "accountId": { "type": "string", "format": "uuid" }, "platform": { "type": "string" }, "username": { "type": "string" }, "followers": { "type": [ "integer", "null" ] }, "following": { "type": [ "integer", "null" ] }, "totalPosts": { "type": [ "integer", "null" ] }, "fetchedAt": { "type": [ "string", "null" ], "format": "date-time" } } } }, "totals": { "type": "object", "properties": { "followers": { "type": "integer" }, "totalPosts": { "type": "integer" } } } } } }, "required": [ "data" ] }, "AccountSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspaceId": { "type": "string", "format": "uuid" }, "platform": { "type": "string" }, "username": { "type": "string" }, "name": { "type": "string" }, "avatar": { "type": [ "string", "null" ] }, "isPrimary": { "type": "boolean" }, "active": { "type": "boolean" }, "healthStatus": { "type": [ "string", "null" ], "enum": [ "healthy", "degraded", "expired", "revoked", "unknown", null ] }, "lastHealthCheck": { "type": [ "string", "null" ], "format": "date-time" } } }, "AccountCreated": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "platform": { "type": "string" }, "username": { "type": "string" }, "name": { "type": "string" }, "avatar": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "AccountDetail": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "platform": { "type": "string" }, "username": { "type": "string" }, "name": { "type": "string" }, "avatar": { "type": [ "string", "null" ] }, "workspace": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "type": { "type": "string" } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "AccountHealth": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "platform": { "type": "string" }, "username": { "type": "string" }, "active": { "type": "boolean" }, "healthStatus": { "type": [ "string", "null" ], "enum": [ "healthy", "degraded", "expired", "revoked", "unknown", null ] }, "lastHealthCheck": { "type": [ "string", "null" ], "format": "date-time" } } }, "AccountsHealthSummaryResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspaceId": { "type": "string", "format": "uuid" }, "platform": { "type": "string" }, "username": { "type": "string" }, "healthStatus": { "type": "string", "enum": [ "healthy", "degraded", "expired", "revoked", "unknown" ] }, "lastHealthCheck": { "type": [ "string", "null" ], "format": "date-time" } } } }, "summary": { "type": "object", "properties": { "total": { "type": "integer" }, "healthy": { "type": "integer" }, "degraded": { "type": "integer" }, "expired": { "type": "integer" }, "revoked": { "type": "integer" }, "unknown": { "type": "integer" } } } } } }, "required": [ "data" ] }, "Community": { "type": "object", "properties": { "id": { "type": "integer", "description": "Internal id (use for delete)" }, "accountId": { "type": "string", "format": "uuid" }, "communityId": { "type": "string", "description": "X community id" }, "name": { "type": "string" }, "memberCount": { "type": [ "integer", "null" ] }, "description": { "type": [ "string", "null" ] }, "imageUrl": { "type": [ "string", "null" ] }, "lastSyncedAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } }, "description": "X (Twitter) community linked to a connected account" }, "LabelWorkspaceRef": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "type": { "type": "string" }, "logo": { "type": [ "string", "null" ] }, "timezone": { "type": "string" }, "language": { "type": "string" } } }, "Label": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "type": "string", "description": "Hex color, e.g. #ff0000" }, "workspace": { "oneOf": [ { "$ref": "#/components/schemas/LabelWorkspaceRef" }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "color", "workspace" ] }, "LabelListItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "type": "string" }, "workspace": { "oneOf": [ { "$ref": "#/components/schemas/LabelWorkspaceRef" }, { "type": "null" } ] } }, "required": [ "id", "name", "color", "workspace" ] }, "WebhookEvent": { "type": "string", "enum": [ "post.published", "post.failed", "post.partially_failed", "delivery.published", "delivery.failed", "delivery.delayed", "account.health_changed" ] }, "Webhook": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspaceId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEvent" } }, "active": { "type": "boolean" }, "lastTriggeredAt": { "type": [ "string", "null" ], "format": "date-time" }, "failureCount": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" } } }, "WebhookCreated": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspaceId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "secret": { "type": "string", "description": "Signing secret for verifying webhook payloads. Returned only once, on creation." }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEvent" } }, "active": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "workspaceId", "url", "secret", "events", "active" ] }, "WebhookUpdated": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspaceId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEvent" } }, "active": { "type": "boolean" }, "failureCount": { "type": "integer" } } }, "AnalyticsOverviewResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "totalAccounts": { "type": "integer" }, "totalFollowers": { "type": "integer" }, "totalPosts": { "type": "integer", "description": "Posts observed in the selected period" }, "totalEngagement": { "type": "integer" }, "totalImpressions": { "type": "integer" }, "totalReach": { "type": "integer" }, "totalLikes": { "type": "integer" }, "totalComments": { "type": "integer" }, "totalShares": { "type": "integer" }, "totalReposts": { "type": "integer" }, "totalSaves": { "type": "integer" }, "totalClicks": { "type": "integer" }, "totalVideoViews": { "type": "integer" }, "totalProfileViews": { "type": "integer" }, "engagementRate": { "type": [ "number", "null" ], "description": "Engagement / reach (or impressions); null without data" }, "deltas": { "type": "object", "properties": { "followers": { "type": [ "number", "null" ] }, "posts": { "type": [ "number", "null" ] }, "engagement": { "type": [ "number", "null" ] }, "impressions": { "type": [ "number", "null" ] }, "likes": { "type": [ "number", "null" ] }, "comments": { "type": [ "number", "null" ] }, "shares": { "type": [ "number", "null" ] }, "profileViews": { "type": [ "number", "null" ] } }, "description": "Percentage change vs the previous period. Post-level metric deltas are always null (platforms only expose lifetime counts per post)." }, "todayStats": { "type": "object", "properties": { "posts": { "type": "integer" }, "followerChange": { "type": "integer" }, "engagement": { "type": "integer" } } }, "platforms": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "accounts": { "type": "integer" }, "followers": { "type": "integer" } } } }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "accountId": { "type": "string", "format": "uuid" }, "platform": { "type": "string" }, "username": { "type": "string" }, "name": { "type": "string" }, "avatar": { "type": [ "string", "null" ] }, "followers": { "type": [ "integer", "null" ] }, "totalPosts": { "type": [ "integer", "null" ] }, "fetchedAt": { "type": [ "string", "null" ], "format": "date-time" }, "history": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "followers": { "type": [ "integer", "null" ] } } }, "description": "Daily follower history (up to 30 days, oldest first)" } } } } } } }, "required": [ "data" ] }, "TimeSeriesResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "days": { "type": "integer" }, "series": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "engagements": { "type": "integer" }, "impressions": { "type": "integer" }, "likes": { "type": "integer" }, "comments": { "type": "integer" }, "shares": { "type": "integer" }, "followers": { "type": "integer" }, "posts": { "type": "integer" } } } } } } }, "required": [ "data" ] }, "TopPost": { "type": "object", "properties": { "rank": { "type": "integer" }, "postId": { "type": [ "string", "null" ], "format": "uuid", "description": "OwlStack post id, or null for platform-native posts" }, "externalPostId": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "owlstack", "platform" ] }, "preview": { "type": [ "string", "null" ], "description": "First 200 characters of the post text" }, "permalink": { "type": [ "string", "null" ] }, "thumbnailUrl": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "platforms": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "username": { "type": "string" }, "url": { "type": [ "string", "null" ] } } } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "type": "string" } } }, "description": "Labels on the post — always empty for platform-native posts" }, "metrics": { "type": "object", "properties": { "engagements": { "type": "integer" }, "impressions": { "type": "integer" }, "reach": { "type": "integer" }, "likes": { "type": "integer" }, "comments": { "type": "integer" }, "shares": { "type": "integer" }, "reposts": { "type": "integer" }, "clicks": { "type": "integer" }, "saves": { "type": "integer" }, "videoViews": { "type": "integer" } } } } }, "LabelAnalytics": { "type": "object", "properties": { "labelId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "type": "string" }, "postCount": { "type": "integer" }, "impressions": { "type": "integer" }, "reach": { "type": "integer" }, "engagements": { "type": "integer" }, "likes": { "type": "integer" }, "comments": { "type": "integer" }, "shares": { "type": "integer" }, "engagementRate": { "type": [ "number", "null" ], "description": "Engagements over reach, falling back to impressions; null when neither exists" }, "followerDelta": { "type": [ "integer", "null" ], "description": "Follows gained across the campaign, or null when no platform reports it" } } }, "PostsTableResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "posts": { "type": "array", "items": { "type": "object", "properties": { "postId": { "type": "string", "format": "uuid" }, "preview": { "type": [ "string", "null" ], "description": "First 120 characters of the post text" }, "status": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "scheduledAt": { "type": [ "string", "null" ], "format": "date-time" }, "platforms": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "username": { "type": "string" }, "url": { "type": [ "string", "null" ] }, "deliveryStatus": { "type": "string", "enum": [ "pending", "queued", "delayed", "publishing", "published", "failed", "cancelled" ] } } } }, "deliverySummary": { "type": "object", "properties": { "total": { "type": "integer" }, "published": { "type": "integer" }, "failed": { "type": "integer" }, "pending": { "type": "integer" } } } } } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "statusSummary": { "type": "object", "properties": { "draft": { "type": "integer" }, "scheduled": { "type": "integer" }, "published": { "type": "integer" }, "failed": { "type": "integer" }, "pending": { "type": "integer" }, "total": { "type": "integer" } } } } } }, "required": [ "data" ] }, "PostingStreakResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "streak": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "count": { "type": "integer" }, "publishedCount": { "type": "integer" }, "failedCount": { "type": "integer" }, "scheduledCount": { "type": "integer" } } } } } } }, "required": [ "data" ] }, "DemographicsBucket": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "number" }, "share": { "type": "number", "description": "Fraction of the dimension total (0-1)" } }, "required": [ "key", "value", "share" ] }, "DemographicsResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "audience": { "type": "string", "enum": [ "followers", "engaged", "reached" ] }, "dimensions": { "type": "object", "properties": { "age": { "type": "array", "items": { "$ref": "#/components/schemas/DemographicsBucket" } }, "gender": { "type": "array", "items": { "$ref": "#/components/schemas/DemographicsBucket" } }, "country": { "type": "array", "items": { "$ref": "#/components/schemas/DemographicsBucket" } }, "city": { "type": "array", "items": { "$ref": "#/components/schemas/DemographicsBucket" } } } }, "contributingAccounts": { "type": "array", "items": { "type": "object", "properties": { "accountId": { "type": "string", "format": "uuid" }, "platform": { "type": "string" }, "username": { "type": "string" } } } }, "unsupportedAccounts": { "type": "array", "items": { "type": "object", "properties": { "accountId": { "type": "string", "format": "uuid" }, "platform": { "type": "string" }, "username": { "type": "string" } } } } } } }, "required": [ "data" ] }, "CollectSummaryResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "accounts": { "type": "integer", "description": "Accounts refreshed" }, "posts": { "type": "integer", "description": "Post metrics collected" }, "demographics": { "type": "integer" }, "errors": { "type": "integer" }, "errorDetails": { "type": "array", "items": { "type": "object", "properties": { "accountId": { "type": "string", "format": "uuid" }, "platform": { "type": "string" }, "username": { "type": "string" }, "stage": { "type": "string", "enum": [ "account", "demographics", "timeline", "post" ] }, "message": { "type": "string" } } } } } } }, "required": [ "data" ] }, "AccountAnalyticsHistoryResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "accountId": { "type": "string", "format": "uuid" }, "platform": { "type": "string" }, "username": { "type": "string" }, "history": { "type": "array", "items": { "type": "object", "properties": { "followers": { "type": [ "integer", "null" ] }, "following": { "type": [ "integer", "null" ] }, "totalPosts": { "type": [ "integer", "null" ] }, "reach": { "type": [ "integer", "null" ] }, "profileViews": { "type": [ "integer", "null" ] }, "fetchedAt": { "type": "string", "format": "date-time" } } } } } } }, "required": [ "data" ] }, "AutomationStep": { "type": "object", "properties": { "id": { "type": "integer" }, "position": { "type": "integer" }, "actionType": { "type": "string", "enum": [ "publish", "delay", "transform" ] }, "actionConfig": { "type": "object", "additionalProperties": true } } }, "Automation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspaceId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "triggerType": { "type": "string", "enum": [ "cross_post", "rss_feed", "api_webhook", "schedule" ] }, "triggerConfig": { "type": "object", "additionalProperties": true }, "active": { "type": "boolean" }, "lastTriggeredAt": { "type": [ "string", "null" ], "format": "date-time" }, "runCount": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "AutomationCreated": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspaceId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "triggerType": { "type": "string", "enum": [ "cross_post", "rss_feed", "api_webhook", "schedule" ] }, "triggerConfig": { "type": "object", "additionalProperties": true }, "active": { "type": "boolean" }, "secret": { "type": "string", "description": "Secret for the webhook trigger endpoint (`x-automation-secret` header). Returned only on creation." }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/AutomationStep" } }, "createdAt": { "type": "string", "format": "date-time" } } }, "AutomationDetail": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspaceId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "triggerType": { "type": "string", "enum": [ "cross_post", "rss_feed", "api_webhook", "schedule" ] }, "triggerConfig": { "type": "object", "additionalProperties": true }, "active": { "type": "boolean" }, "lastTriggeredAt": { "type": [ "string", "null" ], "format": "date-time" }, "runCount": { "type": "integer" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/AutomationStep" } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "AutomationRun": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string" }, "currentStep": { "type": [ "integer", "null" ] }, "triggerEvent": { "type": [ "object", "null" ], "additionalProperties": true }, "startedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "errorMessage": { "type": [ "string", "null" ] } } }, "AutomationRunDetail": { "type": "object", "properties": { "id": { "type": "integer" }, "automationId": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "currentStep": { "type": [ "integer", "null" ] }, "triggerEvent": { "type": [ "object", "null" ], "additionalProperties": true }, "context": { "type": [ "object", "null" ], "additionalProperties": true }, "startedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "errorMessage": { "type": [ "string", "null" ] }, "logs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "stepPosition": { "type": "integer" }, "status": { "type": "string" }, "inputSnapshot": { "type": [ "object", "null" ], "additionalProperties": true }, "outputSnapshot": { "type": [ "object", "null" ], "additionalProperties": true }, "startedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "durationMs": { "type": [ "integer", "null" ] }, "errorMessage": { "type": [ "string", "null" ] } } } } } }, "AutomationStatsResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "totalAutomations": { "type": "integer" }, "activeAutomations": { "type": "integer" }, "totalRuns24h": { "type": "integer", "description": "Runs started in the last 24 hours" }, "runsByStatus": { "type": "object", "additionalProperties": { "type": "integer" } }, "recentRuns": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "automationId": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" } } } } } } }, "required": [ "data" ] }, "MediaLibraryItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "userId": { "type": "string", "format": "uuid" }, "workspaceId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "type": { "type": "string", "enum": [ "image", "video", "gif", "document" ] }, "mimeType": { "type": "string" }, "size": { "type": "integer", "description": "File size in bytes" }, "altText": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" } } }, "UploadedMedia": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Media library id (present when workspaceId was provided)" }, "type": { "type": "string", "enum": [ "image", "video", "gif", "document" ] }, "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "size": { "type": "integer" } }, "required": [ "type", "name", "url", "size" ] } }, "responses": { "Unauthorized": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "The API key lacks the required scope, or a mutating route was called without an active subscription (`subscription_required`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Resource not found or not accessible to the authenticated user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ValidationError": { "description": "Request body or parameters failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "InvalidId": { "description": "Malformed id path parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "Too many requests for this API key in the current minute. The body carries `retry_after` (seconds) and the response carries `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }