{ "openapi": "3.1.0", "info": { "title": "Feedigy", "version": "1.0.0", "description": "Feedigy public API v1. Bearer tokens only; versioned path; cursor pagination; idempotent writes; signed event webhooks." }, "servers": [ { "url": "https://api.feedigy.com/v1", "description": "Production" } ], "security": [ { "bearer": [] } ], "paths": { "/me": { "get": { "operationId": "v1.me", "tags": [ "Me" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "plan": { "type": [ "string", "null" ] }, "limits": { "type": "object", "properties": { "api_requests_per_minute": { "type": [ "integer", "null" ] } }, "required": [ "api_requests_per_minute" ] } }, "required": [ "id", "email", "plan", "limits" ] } }, "required": [ "data" ] } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-RateLimit-Limit": { "description": "Per-minute budget for this token owner (plan tier; unlimited plans report the 3000 protective ceiling).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current 60 s window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "ULID tracing this request in server logs.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "bearer": [ "account:read" ] } ] } }, "/feeds": { "get": { "operationId": "v1.feeds.index", "tags": [ "Feed" ], "parameters": [ { "name": "type", "in": "query", "description": "Comma-separated feed types: original, smart, discovery, imported.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Feed status.", "schema": { "type": "string", "enum": [ "active", "inactive" ] } }, { "name": "search", "in": "query", "description": "Substring search over feed titles.", "schema": { "type": "string" } }, { "name": "tag", "in": "query", "description": "Comma-separated owned tag ids (1–50).", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "description": "Opaque signed cursor from the previous page meta. Omit for the first page.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "description": "Page size, 1–100. Default 25.", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "public_id": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "original", "smart", "discovery", "imported" ] }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "description": { "type": [ "string", "null" ] }, "image_url": { "type": [ "string", "null" ] }, "source_url": { "type": [ "string", "null" ] }, "source_name": { "type": [ "string", "null" ] }, "settings": { "type": [ "object", "null" ], "description": "Discovery-catalog stats subset (language, per_week, partial, subscribers). Null for other feed types." }, "item_count": { "type": "integer" }, "created_at": { "type": [ "string", "null" ] }, "last_synced_at": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "color": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "slug", "color" ] } } }, "required": [ "id", "public_id", "title", "slug", "type", "status", "description", "image_url", "source_url", "source_name", "settings", "item_count", "created_at", "last_synced_at", "tags" ] } }, "meta": { "type": "object", "properties": { "per_page": { "type": "integer" }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "per_page", "next_cursor", "has_more" ] } }, "required": [ "data", "meta" ] } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-RateLimit-Limit": { "description": "Per-minute budget for this token owner (plan tier; unlimited plans report the 3000 protective ceiling).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current 60 s window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "ULID tracing this request in server logs.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "bearer": [ "feeds:read" ] } ] }, "post": { "operationId": "v1.feeds.store", "tags": [ "Feed" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Required. 1–255 printable ASCII characters. Replaying a key returns the original response; a different request under the same key is a 422. Kept 24 h.", "schema": { "type": "string", "pattern": "^[\\x21-\\x7e]+$", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreFeedRequest" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "public_id": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "description": { "type": "string" }, "image_url": { "type": [ "string", "null" ] }, "source_url": { "type": [ "string", "null" ] }, "source_name": { "type": [ "null", "array", "string", "integer", "object" ] }, "settings": { "type": [ "array", "null" ], "items": {} }, "item_count": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "last_synced_at": { "type": [ "string", "null" ] }, "tags": { "type": [ "string", "object" ] } }, "required": [ "id", "public_id", "title", "slug", "type", "status", "description", "image_url", "source_url", "source_name", "settings", "item_count", "created_at", "last_synced_at", "tags" ] } }, "required": [ "data" ] } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "Location": { "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Per-minute budget for this token owner (plan tier; unlimited plans report the 3000 protective ceiling).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current 60 s window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "ULID tracing this request in server logs.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/MalformedJson" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "bearer": [ "feeds:write" ] } ] } }, "/feeds/{feed}": { "get": { "operationId": "v1.feeds.show", "tags": [ "Feed" ], "parameters": [ { "name": "feed", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "public_id": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "original", "smart", "discovery", "imported" ] }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "description": { "type": [ "string", "null" ] }, "image_url": { "type": [ "string", "null" ] }, "source_url": { "type": [ "string", "null" ] }, "source_name": { "type": [ "string", "null" ] }, "settings": { "type": [ "object", "null" ], "description": "Discovery-catalog stats subset (language, per_week, partial, subscribers). Null for other feed types." }, "item_count": { "type": "integer" }, "created_at": { "type": [ "string", "null" ] }, "last_synced_at": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "color": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "slug", "color" ] } } }, "required": [ "id", "public_id", "title", "slug", "type", "status", "description", "image_url", "source_url", "source_name", "settings", "item_count", "created_at", "last_synced_at", "tags" ] } }, "required": [ "data" ] } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-RateLimit-Limit": { "description": "Per-minute budget for this token owner (plan tier; unlimited plans report the 3000 protective ceiling).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current 60 s window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "ULID tracing this request in server logs.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "bearer": [ "feeds:read" ] } ] }, "patch": { "operationId": "v1.feeds.update", "tags": [ "Feed" ], "parameters": [ { "name": "feed", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Required. 1–255 printable ASCII characters. Replaying a key returns the original response; a different request under the same key is a 422. Kept 24 h.", "schema": { "type": "string", "pattern": "^[\\x21-\\x7e]+$", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateFeedRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": {} } }, "required": [ "data" ] } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-RateLimit-Limit": { "description": "Per-minute budget for this token owner (plan tier; unlimited plans report the 3000 protective ceiling).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current 60 s window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "ULID tracing this request in server logs.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/MalformedJson" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "bearer": [ "feeds:write" ] } ] }, "delete": { "operationId": "v1.feeds.destroy", "tags": [ "Feed" ], "parameters": [ { "name": "feed", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "description": "Optional. Same semantics as POST/PATCH when present; without it a repeat DELETE meets the already-deleted record as a 404.", "schema": { "type": "string", "pattern": "^[\\x21-\\x7e]+$", "minLength": 1, "maxLength": 255 } } ], "responses": { "204": { "description": "No content", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-RateLimit-Limit": { "description": "Per-minute budget for this token owner (plan tier; unlimited plans report the 3000 protective ceiling).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current 60 s window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "ULID tracing this request in server logs.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/MalformedJson" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "bearer": [ "feeds:write" ] } ] } }, "/feeds/{feed}/items": { "get": { "operationId": "v1.feeds.items.index", "description": "Items of Original feeds additionally require the posts:read ability.", "tags": [ "FeedItem" ], "parameters": [ { "name": "feed", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "description": "Opaque signed cursor from the previous page meta. Omit for the first page.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "description": "Page size, 1–100. Default 25.", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "feed_id": { "type": "string" }, "guid": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string" }, "status": { "type": "string" }, "url": { "type": [ "string", "null" ] }, "original_url": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "body": { "type": "string" }, "image_url": { "type": [ "string", "null" ] }, "source_title": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "author": { "type": "string" }, "categories": { "type": "string" }, "published_at": { "type": [ "string", "null" ] }, "scheduled_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] }, "feed": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" } }, "required": [ "id", "title" ] }, { "type": "null" }, { "type": "object" } ] }, "tags": { "type": [ "string", "object" ] } }, "required": [ "id", "feed_id", "guid", "title", "slug", "status", "url", "original_url", "description", "body", "image_url", "source_title", "source_url", "author", "categories", "published_at", "scheduled_at", "created_at", "updated_at", "feed", "tags" ] } }, "meta": { "type": "object", "properties": { "per_page": { "type": "integer" }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "per_page", "next_cursor", "has_more" ] } }, "required": [ "data", "meta" ] }, { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0 }, "meta": { "type": "object", "properties": { "per_page": { "type": "integer" }, "next_cursor": { "type": "null" }, "has_more": { "type": "boolean" } }, "required": [ "per_page", "next_cursor", "has_more" ] } }, "required": [ "data", "meta" ] } ] } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-RateLimit-Limit": { "description": "Per-minute budget for this token owner (plan tier; unlimited plans report the 3000 protective ceiling).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current 60 s window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "ULID tracing this request in server logs.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "bearer": [ "feeds:read" ] } ] } }, "/posts": { "get": { "operationId": "v1.posts.index", "tags": [ "Post" ], "parameters": [ { "name": "feed", "in": "query", "description": "Restrict to one owned Original feed.", "schema": { "type": "integer" } }, { "name": "status", "in": "query", "description": "Post status.", "schema": { "type": "string", "enum": [ "published", "scheduled", "draft" ] } }, { "name": "cursor", "in": "query", "description": "Opaque signed cursor from the previous page meta. Omit for the first page.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "description": "Page size, 1–100. Default 25.", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "description": "Null for smart-feed snapshot rows, which have no database id — `guid` is the stable identity there." }, "feed_id": { "type": "integer" }, "guid": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "slug": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "published", "scheduled", "draft" ] }, "url": { "type": [ "string", "null" ] }, "original_url": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "body": { "type": [ "string", "null" ] }, "image_url": { "type": [ "string", "null" ] }, "source_title": { "type": [ "string", "null" ] }, "source_url": { "type": [ "string", "null" ] }, "author": { "type": [ "string", "null" ] }, "categories": { "type": [ "array", "null" ], "items": { "type": "string" } }, "published_at": { "type": [ "string", "null" ] }, "scheduled_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "id", "feed_id", "guid", "title", "slug", "status", "url", "original_url", "description", "body", "image_url", "source_title", "source_url", "author", "categories", "published_at", "scheduled_at", "created_at", "updated_at" ] } }, "meta": { "type": "object", "properties": { "per_page": { "type": "integer" }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "per_page", "next_cursor", "has_more" ] } }, "required": [ "data", "meta" ] } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-RateLimit-Limit": { "description": "Per-minute budget for this token owner (plan tier; unlimited plans report the 3000 protective ceiling).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current 60 s window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "ULID tracing this request in server logs.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "bearer": [ "posts:read" ] } ] }, "post": { "operationId": "v1.posts.store", "tags": [ "Post" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Required. 1–255 printable ASCII characters. Replaying a key returns the original response; a different request under the same key is a 422. Kept 24 h.", "schema": { "type": "string", "pattern": "^[\\x21-\\x7e]+$", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorePostRequest" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "feed_id": { "type": "string" }, "guid": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string" }, "status": { "type": "string" }, "url": { "type": [ "string", "null" ] }, "original_url": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "body": { "type": "string" }, "image_url": { "type": [ "string", "null" ] }, "source_title": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "author": { "type": "string" }, "categories": { "type": "string" }, "published_at": { "type": [ "string", "null" ] }, "scheduled_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] }, "feed": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" } }, "required": [ "id", "title" ] }, { "type": "null" }, { "type": "object" } ] }, "tags": { "type": [ "string", "object" ] } }, "required": [ "id", "feed_id", "guid", "title", "slug", "status", "url", "original_url", "description", "body", "image_url", "source_title", "source_url", "author", "categories", "published_at", "scheduled_at", "created_at", "updated_at", "feed", "tags" ] } }, "required": [ "data" ] } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "Location": { "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Per-minute budget for this token owner (plan tier; unlimited plans report the 3000 protective ceiling).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current 60 s window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "ULID tracing this request in server logs.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/MalformedJson" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "bearer": [ "posts:write" ] } ] } }, "/posts/{post}": { "get": { "operationId": "v1.posts.show", "tags": [ "Post" ], "parameters": [ { "name": "post", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "description": "Null for smart-feed snapshot rows, which have no database id — `guid` is the stable identity there." }, "feed_id": { "type": "integer" }, "guid": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "slug": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "published", "scheduled", "draft" ] }, "url": { "type": [ "string", "null" ] }, "original_url": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "body": { "type": [ "string", "null" ] }, "image_url": { "type": [ "string", "null" ] }, "source_title": { "type": [ "string", "null" ] }, "source_url": { "type": [ "string", "null" ] }, "author": { "type": [ "string", "null" ] }, "categories": { "type": [ "array", "null" ], "items": { "type": "string" } }, "published_at": { "type": [ "string", "null" ] }, "scheduled_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "id", "feed_id", "guid", "title", "slug", "status", "url", "original_url", "description", "body", "image_url", "source_title", "source_url", "author", "categories", "published_at", "scheduled_at", "created_at", "updated_at" ] } }, "required": [ "data" ] } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-RateLimit-Limit": { "description": "Per-minute budget for this token owner (plan tier; unlimited plans report the 3000 protective ceiling).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current 60 s window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "ULID tracing this request in server logs.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "bearer": [ "posts:read" ] } ] }, "patch": { "operationId": "v1.posts.update", "tags": [ "Post" ], "parameters": [ { "name": "post", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Required. 1–255 printable ASCII characters. Replaying a key returns the original response; a different request under the same key is a 422. Kept 24 h.", "schema": { "type": "string", "pattern": "^[\\x21-\\x7e]+$", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePostRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": {} } }, "required": [ "data" ] } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-RateLimit-Limit": { "description": "Per-minute budget for this token owner (plan tier; unlimited plans report the 3000 protective ceiling).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current 60 s window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "ULID tracing this request in server logs.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/MalformedJson" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "bearer": [ "posts:write" ] } ] }, "delete": { "operationId": "v1.posts.destroy", "tags": [ "Post" ], "parameters": [ { "name": "post", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "description": "Optional. Same semantics as POST/PATCH when present; without it a repeat DELETE meets the already-deleted record as a 404.", "schema": { "type": "string", "pattern": "^[\\x21-\\x7e]+$", "minLength": 1, "maxLength": 255 } } ], "responses": { "204": { "description": "No content", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-RateLimit-Limit": { "description": "Per-minute budget for this token owner (plan tier; unlimited plans report the 3000 protective ceiling).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current 60 s window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "ULID tracing this request in server logs.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/MalformedJson" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "bearer": [ "posts:write" ] } ] } }, "/channels": { "get": { "operationId": "v1.channels.index", "tags": [ "Channel" ], "parameters": [ { "name": "cursor", "in": "query", "description": "Opaque signed cursor from the previous page meta. Omit for the first page.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "description": "Page size, 1–100. Default 25.", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "public_id": { "type": "string" }, "channel_id": { "type": [ "string", "null" ] }, "provider": { "type": "string" }, "name": { "type": "string" }, "avatar_url": { "type": [ "string", "null" ] }, "public_url": { "type": [ "string", "null" ] }, "target_kind": { "type": [ "string", "null" ] }, "capabilities": { "type": "array", "items": { "type": "string" } }, "connected_at": { "type": [ "string", "null" ] }, "needs_reconnect": { "type": "boolean" }, "verified": { "type": [ "boolean", "null" ] }, "overage_disabled": { "type": "boolean" } }, "required": [ "id", "public_id", "channel_id", "provider", "name", "avatar_url", "public_url", "target_kind", "capabilities", "connected_at", "needs_reconnect", "verified", "overage_disabled" ] } }, "meta": { "type": "object", "properties": { "per_page": { "type": "integer" }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "per_page", "next_cursor", "has_more" ] } }, "required": [ "data", "meta" ] } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-RateLimit-Limit": { "description": "Per-minute budget for this token owner (plan tier; unlimited plans report the 3000 protective ceiling).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current 60 s window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "ULID tracing this request in server logs.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "bearer": [ "channels:read" ] } ] } }, "/publishers": { "get": { "operationId": "v1.publishers.index", "tags": [ "Publisher" ], "parameters": [ { "name": "cursor", "in": "query", "description": "Opaque signed cursor from the previous page meta. Omit for the first page.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "description": "Page size, 1–100. Default 25.", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "public_id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "running", "paused", "error" ] }, "destination": { "type": "string" }, "timezone": { "type": "string" }, "schedule_type": { "type": "string" }, "start_at": { "type": [ "string", "null" ] }, "stop_at": { "type": [ "string", "null" ] }, "next_run_at": { "type": [ "string", "null" ] }, "last_run_at": { "type": [ "string", "null" ] }, "consecutive_failures": { "type": "integer" }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] }, "feeds_count": { "type": "integer" }, "feeds": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "public_id": { "type": "string" }, "title": { "type": "string" }, "image_url": { "type": [ "string", "null" ] }, "source_url": { "type": [ "string", "null" ] } }, "required": [ "id", "public_id", "title", "image_url", "source_url" ] } } }, "required": [ "id", "public_id", "name", "status", "destination", "timezone", "schedule_type", "start_at", "stop_at", "next_run_at", "last_run_at", "consecutive_failures", "created_at", "updated_at", "feeds_count", "feeds" ] } }, "meta": { "type": "object", "properties": { "per_page": { "type": "integer" }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "per_page", "next_cursor", "has_more" ] } }, "required": [ "data", "meta" ] } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-RateLimit-Limit": { "description": "Per-minute budget for this token owner (plan tier; unlimited plans report the 3000 protective ceiling).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current 60 s window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "ULID tracing this request in server logs.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "bearer": [ "publishers:read" ] } ] } }, "/publishers/{publisher}": { "get": { "operationId": "v1.publishers.show", "tags": [ "Publisher" ], "parameters": [ { "name": "publisher", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "public_id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "running", "paused", "error" ] }, "destination": { "type": "string" }, "timezone": { "type": "string" }, "schedule_type": { "type": "string" }, "start_at": { "type": [ "string", "null" ] }, "stop_at": { "type": [ "string", "null" ] }, "next_run_at": { "type": [ "string", "null" ] }, "last_run_at": { "type": [ "string", "null" ] }, "consecutive_failures": { "type": "integer" }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] }, "feeds_count": { "type": "integer" }, "feeds": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "public_id": { "type": "string" }, "title": { "type": "string" }, "image_url": { "type": [ "string", "null" ] }, "source_url": { "type": [ "string", "null" ] } }, "required": [ "id", "public_id", "title", "image_url", "source_url" ] } } }, "required": [ "id", "public_id", "name", "status", "destination", "timezone", "schedule_type", "start_at", "stop_at", "next_run_at", "last_run_at", "consecutive_failures", "created_at", "updated_at", "feeds_count", "feeds" ] } }, "required": [ "data" ] } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-RateLimit-Limit": { "description": "Per-minute budget for this token owner (plan tier; unlimited plans report the 3000 protective ceiling).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current 60 s window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "ULID tracing this request in server logs.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "bearer": [ "publishers:read" ] } ] } }, "/tags": { "get": { "operationId": "v1.tags.index", "tags": [ "Tag" ], "parameters": [ { "name": "cursor", "in": "query", "description": "Opaque signed cursor from the previous page meta. Omit for the first page.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "description": "Page size, 1–100. Default 25.", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "color": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "slug", "color" ] } }, "meta": { "type": "object", "properties": { "per_page": { "type": "integer" }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "per_page", "next_cursor", "has_more" ] } }, "required": [ "data", "meta" ] } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-RateLimit-Limit": { "description": "Per-minute budget for this token owner (plan tier; unlimited plans report the 3000 protective ceiling).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current 60 s window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "ULID tracing this request in server logs.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "bearer": [ "feeds:read" ] } ] } } }, "components": { "securitySchemes": { "bearer": { "type": "http", "description": "Create a token in Settings → API. Send it as `Authorization: Bearer `. No cookies, no CSRF.", "scheme": "bearer", "bearerFormat": "Sanctum personal access token" } }, "schemas": { "StoreFeedRequest": { "type": "object", "description": "v1 Original Feed creation (Phase 2 slice 4). Feeds are always created\nactive; the slug is auto-generated unless the client names a free one.", "properties": { "title": { "type": "string", "maxLength": 255 }, "slug": { "type": [ "string", "null" ], "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "maxLength": 100 }, "description": { "type": [ "string", "null" ], "maxLength": 5000 }, "tag_ids": { "type": [ "array", "null" ], "items": { "type": "integer", "minimum": 1 }, "maxItems": 20 }, "image_url": { "type": [ "string", "null" ], "maxLength": 2048 } }, "required": [ "title" ], "title": "StoreFeedRequest" }, "StorePostRequest": { "type": "object", "description": "v1 post creation (Phase 2 slice 4). A literal `status` drives the write;\n`slug`, `body`, `author`, `tags`, `image_url` follow the web column bounds\n(tags arrive as owned ids, capped like the web picker's 20). Anything not\nlisted here — provider metadata, editor state, uploads — is a 422.", "properties": { "feed_id": { "type": "integer", "minimum": 1 }, "title": { "type": "string", "maxLength": 255 }, "slug": { "type": [ "string", "null" ], "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "maxLength": 100 }, "body": { "type": [ "string", "null" ], "maxLength": 131072 }, "author": { "type": [ "string", "null" ], "maxLength": 255 }, "tag_ids": { "type": [ "array", "null" ], "items": { "type": "integer", "minimum": 1 }, "maxItems": 20 }, "image_url": { "type": [ "string", "null" ], "maxLength": 2048 }, "status": { "type": "string", "enum": [ "published", "scheduled", "draft" ] }, "scheduled_at": { "type": "string" } }, "required": [ "feed_id", "title", "status" ], "title": "StorePostRequest" }, "UpdateFeedRequest": { "type": "object", "description": "v1 Original Feed patch (Phase 2 slice 4). Absent keys keep the stored\nvalue; `null` clears `description` and restores the default `image_url`.", "properties": { "title": { "type": "string", "maxLength": 255 }, "slug": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "maxLength": 100 }, "description": { "type": [ "string", "null" ], "maxLength": 5000 }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "tag_ids": { "type": [ "array", "null" ], "items": { "type": "integer", "minimum": 1 }, "maxItems": 20 }, "image_url": { "type": [ "string", "null" ], "maxLength": 2048 } }, "title": "UpdateFeedRequest" }, "UpdatePostRequest": { "type": "object", "description": "v1 post patch (Phase 2 slice 4). Every key is optional: absent leaves the\nstored value untouched, `null` clears a nullable field. `scheduled_at`\nonly makes sense beside `status: scheduled` in the same payload.", "properties": { "feed_id": { "type": "integer", "minimum": 1 }, "title": { "type": "string", "maxLength": 255 }, "slug": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "maxLength": 100 }, "body": { "type": [ "string", "null" ], "maxLength": 131072 }, "author": { "type": [ "string", "null" ], "maxLength": 255 }, "tag_ids": { "type": [ "array", "null" ], "items": { "type": "integer", "minimum": 1 }, "maxItems": 20 }, "image_url": { "type": [ "string", "null" ], "maxLength": 2048 }, "status": { "type": "string", "enum": [ "published", "scheduled", "draft" ] }, "scheduled_at": { "type": "string" } }, "title": "UpdatePostRequest" }, "WebhookChannelTokenExpired": { "type": "object", "properties": { "event": { "type": "string", "const": "channel.token_expired" }, "event_id": { "type": "string", "description": "Stable id \"channel.token_expired::\" — prefixed, not a bare UUID. Dedupe on this — retries repeat it with the same body." }, "version": { "type": "integer", "description": "Payload version. A breaking shape change ships a new version." }, "occurred_at": { "type": "string", "description": "ISO 8601 UTC timestamp of the source event." }, "data": { "type": "object", "properties": { "integration": { "type": "object", "properties": { "id": { "type": "integer" }, "provider": { "type": "string" }, "label": { "type": "string", "description": "Safe display label — never a credential." } } }, "reason": { "type": "string", "description": "Internal code such as provider_rejected_refresh." } } } }, "required": [ "event", "event_id", "version", "occurred_at", "data" ], "title": "WebhookChannelTokenExpired" }, "WebhookPostPublished": { "type": "object", "properties": { "event": { "type": "string", "const": "post.published" }, "event_id": { "type": "string", "description": "Stable UUID of the publication episode. Dedupe on this — retries repeat it with the same body." }, "version": { "type": "integer", "description": "Payload version. A breaking shape change ships a new version." }, "occurred_at": { "type": "string", "description": "ISO 8601 UTC timestamp of the source event." }, "data": { "type": "object", "properties": { "post": { "type": "object", "properties": { "id": { "type": "integer" }, "guid": { "type": "string" }, "title": { "type": "string" }, "url": { "type": [ "string", "null" ] }, "excerpt": { "type": [ "string", "null" ], "description": "Plain-text excerpt, at most 2000 characters." }, "image_url": { "type": [ "string", "null" ] }, "author": { "type": [ "string", "null" ] }, "published_at": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" }, "maxItems": 50 } } }, "feed": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "url": { "type": [ "string", "null" ] } } } } } }, "required": [ "event", "event_id", "version", "occurred_at", "data" ], "title": "WebhookPostPublished" }, "WebhookPublisherRunFailed": { "type": "object", "properties": { "event": { "type": "string", "const": "publisher.run.failed" }, "event_id": { "type": "string", "description": "Stable id \"publisher.run.failed:\" — prefixed, not a bare UUID. Dedupe on this — retries repeat it with the same body." }, "version": { "type": "integer", "description": "Payload version. A breaking shape change ships a new version." }, "occurred_at": { "type": "string", "description": "ISO 8601 UTC timestamp of the source event." }, "data": { "type": "object", "properties": { "publisher": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "destination": { "type": "string" } } }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "run_failed", "credentials_rejected" ] }, "message": { "type": "string" } } }, "consecutive_failures": { "type": "integer" }, "occurrence_id": { "type": [ "integer", "null" ] } } } }, "required": [ "event", "event_id", "version", "occurred_at", "data" ], "title": "WebhookPublisherRunFailed" } }, "responses": { "Unauthenticated": { "description": "Missing, revoked or expired bearer token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Machine-readable error type.", "const": "unauthenticated" }, "message": { "type": "string", "description": "Missing, revoked or expired bearer token." }, "request_id": { "type": "string", "description": "ULID tracing this request in server logs. Present on every API response, success or failure." } }, "required": [ "type", "message", "request_id" ] } }, "required": [ "error" ] } } }, "headers": { "X-Request-Id": { "description": "ULID tracing this request in server logs.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Per-minute budget for this token owner (plan tier; unlimited plans report the 3000 protective ceiling).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current 60 s window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets.", "schema": { "type": "integer" } } } }, "Forbidden": { "description": "The token lacks the required ability, or the plan grants no API access.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Machine-readable error type.", "const": "forbidden" }, "message": { "type": "string", "description": "The token lacks the required ability, or the plan grants no API access." }, "request_id": { "type": "string", "description": "ULID tracing this request in server logs. Present on every API response, success or failure." } }, "required": [ "type", "message", "request_id" ] } }, "required": [ "error" ] } } }, "headers": { "X-Request-Id": { "description": "ULID tracing this request in server logs.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Per-minute budget for this token owner (plan tier; unlimited plans report the 3000 protective ceiling).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current 60 s window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets.", "schema": { "type": "integer" } } } }, "NotFound": { "description": "No such record for this account. Foreign ids are 404, never 403.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Machine-readable error type.", "const": "not_found" }, "message": { "type": "string", "description": "No such record for this account. Foreign ids are 404, never 403." }, "request_id": { "type": "string", "description": "ULID tracing this request in server logs. Present on every API response, success or failure." } }, "required": [ "type", "message", "request_id" ] } }, "required": [ "error" ] } } }, "headers": { "X-Request-Id": { "description": "ULID tracing this request in server logs.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Per-minute budget for this token owner (plan tier; unlimited plans report the 3000 protective ceiling).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current 60 s window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets.", "schema": { "type": "integer" } } } }, "MalformedJson": { "description": "The request body is not valid JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Machine-readable error type.", "const": "malformed_json" }, "message": { "type": "string", "description": "The request body is not valid JSON." }, "request_id": { "type": "string", "description": "ULID tracing this request in server logs. Present on every API response, success or failure." } }, "required": [ "type", "message", "request_id" ] } }, "required": [ "error" ] } } }, "headers": { "X-Request-Id": { "description": "ULID tracing this request in server logs.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Per-minute budget for this token owner (plan tier; unlimited plans report the 3000 protective ceiling).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current 60 s window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets.", "schema": { "type": "integer" } } } }, "PayloadTooLarge": { "description": "The request body exceeds the 256 KB limit.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Machine-readable error type.", "const": "payload_too_large" }, "message": { "type": "string", "description": "The request body exceeds the 256 KB limit." }, "request_id": { "type": "string", "description": "ULID tracing this request in server logs. Present on every API response, success or failure." } }, "required": [ "type", "message", "request_id" ] } }, "required": [ "error" ] } } }, "headers": { "X-Request-Id": { "description": "ULID tracing this request in server logs.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Per-minute budget for this token owner (plan tier; unlimited plans report the 3000 protective ceiling).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current 60 s window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets.", "schema": { "type": "integer" } } } }, "UnsupportedMediaType": { "description": "Write requests must use Content-Type: application/json.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Machine-readable error type.", "const": "unsupported_media_type" }, "message": { "type": "string", "description": "Write requests must use Content-Type: application/json." }, "request_id": { "type": "string", "description": "ULID tracing this request in server logs. Present on every API response, success or failure." } }, "required": [ "type", "message", "request_id" ] } }, "required": [ "error" ] } } }, "headers": { "X-Request-Id": { "description": "ULID tracing this request in server logs.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Per-minute budget for this token owner (plan tier; unlimited plans report the 3000 protective ceiling).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current 60 s window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets.", "schema": { "type": "integer" } } } }, "IdempotencyConflict": { "description": "A request with this idempotency key is already in progress. Wait a second and retry with the same key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Machine-readable error type.", "const": "idempotency_in_progress" }, "message": { "type": "string", "description": "A request with this idempotency key is already in progress. Wait a second and retry with the same key." }, "request_id": { "type": "string", "description": "ULID tracing this request in server logs. Present on every API response, success or failure." } }, "required": [ "type", "message", "request_id" ] } }, "required": [ "error" ] } } }, "headers": { "X-Request-Id": { "description": "ULID tracing this request in server logs.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Per-minute budget for this token owner (plan tier; unlimited plans report the 3000 protective ceiling).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current 60 s window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets.", "schema": { "type": "integer" } } } }, "ValidationFailed": { "description": "The request was well-formed but semantically invalid. A tampered, foreign or filter-mismatched pagination cursor is an invalid_cursor — start over from the first page. Reusing an idempotency key with a different request is an idempotency_key_reused — mint a fresh key per logical operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Machine-readable error type.", "enum": [ "validation_failed", "invalid_cursor", "idempotency_key_reused" ] }, "message": { "type": "string", "description": "The request was well-formed but semantically invalid. A tampered, foreign or filter-mismatched pagination cursor is an invalid_cursor — start over from the first page. Reusing an idempotency key with a different request is an idempotency_key_reused — mint a fresh key per logical operation." }, "details": { "type": "object", "description": "Field-keyed validation failures. Absent when there is nothing field-specific to report." }, "request_id": { "type": "string", "description": "ULID tracing this request in server logs. Present on every API response, success or failure." } }, "required": [ "type", "message", "request_id" ] } }, "required": [ "error" ] } } }, "headers": { "X-Request-Id": { "description": "ULID tracing this request in server logs.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Per-minute budget for this token owner (plan tier; unlimited plans report the 3000 protective ceiling).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current 60 s window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets.", "schema": { "type": "integer" } } } }, "RateLimited": { "description": "Per-token plan budget exhausted. Back off for Retry-After seconds.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Machine-readable error type.", "const": "rate_limited" }, "message": { "type": "string", "description": "Per-token plan budget exhausted. Back off for Retry-After seconds." }, "request_id": { "type": "string", "description": "ULID tracing this request in server logs. Present on every API response, success or failure." } }, "required": [ "type", "message", "request_id" ] } }, "required": [ "error" ] } } }, "headers": { "X-Request-Id": { "description": "ULID tracing this request in server logs.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Per-minute budget for this token owner (plan tier; unlimited plans report the 3000 protective ceiling).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current 60 s window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds until the next request is admitted.", "schema": { "type": "integer" } } } }, "ServiceUnavailable": { "description": "The API is disabled or rate limiting is temporarily unavailable. Retry with backoff.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Machine-readable error type.", "const": "service_unavailable" }, "message": { "type": "string", "description": "The API is disabled or rate limiting is temporarily unavailable. Retry with backoff." }, "request_id": { "type": "string", "description": "ULID tracing this request in server logs. Present on every API response, success or failure." } }, "required": [ "type", "message", "request_id" ] } }, "required": [ "error" ] } } }, "headers": { "X-Request-Id": { "description": "ULID tracing this request in server logs.", "schema": { "type": "string" } } } } } } }